Another use case for __traits(docComment)

[Steven Schveighoffer]

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.

-Steve