Another use case for __traits(docComment)
schveiguy at gmail.com
Wed Nov 13 17:40:57 UTC 2019
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:
/// $(BADMACRO boo)
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!
More information about the Digitalmars-d