Another use case for __traits(docComment)

[FeepingCreature]

On Wednesday, 13 November 2019 at 16:33:58 UTC, Steven 
Schveighoffer wrote:
> 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.

Easily fixed: make the trait fail if the comment violates the 
Ddoc guidelines.

>
>> 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.

We already require comments to compile correctly. That's what 
Ddoc *is*. Documentation should not be considered an optional 
part of functionality, especially if the user is trying to use 
Ddoc comments.

>
> 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.

That would be nice. However, imagine this usecase: Swagger is a 
documentation format for REST requests. It would be handy if this 
documentation could be served right alongside the requests 
themselves. However, this would require a two-step process where 
the code is compiled, the Ddoc comments are discarded; then the 
code is, for no good reason, compiled again with a separate tool 
that wraps the D compiler, having to ensure it gets the same 
compiler binary and same compiler flags, creating an additional 
point of error (for no reason!), then dynamically loaded back 
into a process and processed at runtime, when they could have 
been equally well evaluated via a trait at compiletime and 
processed in ctfe with std.json to generate static output with 
nicely integrated error checking with line numbers.

>
> 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

Again: Ddoc comments are *already* a mandatory part of 
compilation. If code compiles but the comments violate Ddoc, it 
should under no circumstances be considered "working."
D is a static language. To me, that means: any runtime failure 
that can be a compiletime failure should be. Compilation failing 
is annoying; but, compilation failing *rather than* runtime 
failing is the entire point of static types.