Another use case for __traits(docComment)
schveiguy at gmail.com
Thu Nov 14 14:51:27 UTC 2019
On 11/14/19 2:50 AM, Jonathan Marler wrote:
> That being said, Ddoc comments differ from named parameters. DDoc
> comments are already exposed to the compiler and external tools. Unlike
> parameter names, they are already written to be publicly consumed by
> external components. Adding another access point via __traits is less
> significant since this information is already exposed to other external
> components. DDoc comments are also "opt-in". You can use regular
> comments if you don't want to expose/maintain well-formatted metadata
> about your code.
You aren't exposing anything, as long as you don't include the source.
You can't access the compiler's comment representation. Not only that,
but the compiler doesn't do crap unless you are outputting documents.
The lexer will treat ddoc comments as comments and COMPLETELY IGNORE
THEM unless it is told to deal with them, and even then, all it does is
scrub the comment into a nicer form (removing strings of ***** before
the /, etc.). Then it's up to the document generator to figure it out.
But that should be considered a separate consumer of the comments, not
part of compilation.
> I'd also be careful about thinking about DDoc comments like they are
> "comments". DDoc comments may be called comments but they don't fit the
> criteria of normal comments. They have their own format (a mini
> language within D) and have lexical significance to the compiler. They
> actually behave more like user-defined attributes rather than normal
> comments. I have a feeling that if they were called something else like
> "DDoc Metadata" rather than comments then there wouldn't be much
> resistance to exposing them via __traits.
DDoc comments are not *required* to conform to anything. I can write
whatever I want in a ddoc comment, and the effect is, the doc generator
(when asked to) will generate documentation that includes the symbol
which is associated with the comment. If you write malformed DDoc
comments, it's still valid D code to the compiler.
What goes in that documentation is only going to look nice if you follow
the rules, but they are not really requirements. DDoc still generates as
well as it can if you don't give it well-formed syntax.
Or, you can just use your own doc generator, and leave the compiler out
of it. They are just comments after all, ignored by the compiler for
compiling code (so far).
The thing is, a documentation generator needs a parser (and in D's case,
some semantic analysis for e.g. attribute/type inference) to generate
nice docs. The fact that the compiler already does this helps when
generating documentation, but generating docs is not part of compilation.
Yes, they truly are comments, and in the current state of affairs, a
documentation generator that is included with the compiler can choose to
do something with those comments. The code generating part is, and
should remain, completely oblivious to the comment data.
I'm not going to continue to go around in circles here, comments are
comments and should not affect code. I'd say the options I would agree
with (and take this with the grain of salt that I have literally 0 power
over what actually gets implemented) is:
1. We support fetching ddoc comment data for runtime consumption only
(maybe even the JSON form)
2. We support a ddoc style that is not comments, and that can be both
verified for correctness and accessed via __traits
3. Some really smart person figures out how to use the generated JSON at
runtime and requires no updates from the compiler.
More information about the Digitalmars-d