Another use case for __traits(docComment)

[Steven Schveighoffer]

On 11/13/19 12:19 PM, FeepingCreature wrote:
> On Wednesday, 13 November 2019 at 16:33:58 UTC, Steven Schveighoffer wrote:

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

I'm not convinced:

import std.stdio;

/// $(BADMACRO boo)
void main()
{
     writeln("compiles and runs!");
}

Even generates ddoc! Just that, @(BADMACRO boo) does nothing. It doesn't 
even produce an error.

Let's mess with the parsing:

/// $(BADMACRO boo

note the missing parentheses. No errors, even when compiled with -D. I 
get a correct html doc, but now I see "(BADMACRO boo" as the docs for 
main as if it were just a string (curiously missing the $ but whatevs, 
it's just comments and docs!)

I wouldn't consider this to be "mandatory" or even not "working". I get 
a working binary, and I get a working ddoc (I see main in the docs, and 
the junk that I stuck in there). You want to introduce into this a way 
to create *errors* when existing ddocs don't have to even parse correctly?

The D spec says what DDoc is, but doesn't say that anything has to 
conform to ddoc (indeed, someone might even use another doc system and 
have their comments written for it), or even that DDoc will fail to 
produce documentation if it's not correct!

-Steve