Another use case for __traits(docComment)

[Steven Schveighoffer]

On 11/13/19 11:12 AM, Adam D. Ruppe wrote:
> On Wednesday, 13 November 2019 at 16:03:55 UTC, Steven Schveighoffer wrote:
>> It just shouldn't be a comment, which the compiler is supposed to ignore.
> 
> The D specification makes a distinction between ordinary comments and 
> ddoc comments. ddoc comments are well-defined by the language and 
> attached to symbols by parsing rules.

Well defined, but it still compiles even if you don't follow the spec. 
These are comments still, and a secondary product from the binary output.

> It currently doesn't expose it directly - it only processes it into 
> separate files (not ignoring them!) - but I want to change that, and 
> appealing to the authority of the status quo isn't much of a 
> counterargument.

In reality you could separate the ddoc parsing and generation from the 
compile step anyway. It's just that it's much more convenient to use the 
already parsed AST for the code to generate the documentation.

In this way, the *code* affects the documentation, not the other way 
around. The status quo should remain this way because code is 
complicated enough without requiring comments to "compile" correctly too.

However, I'm OK with something other than comments being used to 
generate the doc reading code, OR deal with it at runtime when the 
compiler is not involved.

Note that ddoc comments are still not ddoc data. You are missing a lot 
of stuff with just the string. Wouldn't it be nice to just import the 
JSON data generated by the compiler? That's how I would do it.

> 
>> The thought of comments *ever* affecting the code is just plain wrong 
>> to me. Comments are not code, we should keep that line bright.
> 
> I agree for regular comments, but ddoc is already a part of the language 
> and processed by the compiler! All I want to do is let other parts of 
> the language see it too.
> 
> And again, UDAs do a better job at embedding non-doc stuff than doc 
> comments. So I really think the risk of people going crazy with them is 
> quite small since the alternative is superior for this task.

I've seen lots of schemes where comments are significant to some process 
or another. IDE directives for instance.

But these schemes can play around in this realm *because* the compiler 
ignores them. I never want to see a case where comments are significant 
and break compilation or introduce bugs. We have enough to review in the 
code itself...

-Steve