Another use case for __traits(docComment)

Steven Schveighoffer schveiguy at
Wed Nov 13 16:03:55 UTC 2019

On 11/12/19 11:23 AM, Adam D. Ruppe wrote:
> On Tuesday, 12 November 2019 at 15:14:17 UTC, Steven Schveighoffer wrote:
>> Alternatively, we could use something other than comments for 
>> documentation. e.g.:
> lol
> @ddoc!q{
> /++
> +/
> }
> that would actually work and the doc generator can recognize the pattern 
> too.
> But there's a big difference:
> struct A {
>     int a; /// does something
> }

This is really not much different:

struct A {
     @ddoc(does something)
     int a;

But I mean, we can do whatever we want. It doesn't have to fit into the 
world of UDA. It can be its own syntax.

struct A {
     int a; !ddoc does something

It just shouldn't be a comment, which the compiler is supposed to ignore.

> And of course, my big use case is to fetch docs for third party libs I'd 
> rather not edit the source of anyway.

Well, assuming this isn't just a mental exercise, the answer would be, 
if you want it to be accessible to __traits(getDocs), you need to write 
it the other way. If that means you can't access the docs, then you 
can't access the docs. I would expect a dfix solution is braindead 
simple here.

> Now see, this is an argument against the fear that it will get abused 
> though simply because the language has easier ways to do other things. 
> Using UDAs for docs is doable but awkward, so we prefer to use /++ +/.
> Similarly, abusing doc comments as UDAs is going to be more awkward than 
> using the real thing - you can use the language to structure it and all. 
> So why do things the hard way when there's an easy way?

The thought of comments *ever* affecting the code is just plain wrong to 
me. Comments are not code, we should keep that line bright.


More information about the Digitalmars-d mailing list