David:

> So no official word to it?

Why don't you write here a list of possible applications (use cases) of your idea?

I hope Andrei will comment a little. It's a very simple additive change, and it looks useful.

Bye,
bearophile

On Monday, 20 August 2012 at 22:41:33 UTC, bearophile wrote:
> I hope Andrei will comment a little. It's a very simple additive change, and it looks useful.


Although I like the idea and wouldn't mind seeing something like this implemented, I disagree that it's a very simple change. It would require that there be some sort of standard for associating comments with their respective methods/structs/classes. See nimrod's [1] way: the comments are actually part of the AST.

[1]: http://nimrod-code.org/manual.html#comments

On Monday, 20 August 2012 at 23:18:28 UTC, Chris Cain wrote:
> Although I like the idea and wouldn't mind seeing something like this implemented, I disagree that it's a very simple change. It would require that there be some sort of standard for associating comments with their respective methods/structs/classes.


http://dlang.org/ddoc.html

dmd -D generates some html output based on comments.

If you do dmd -X -D, the json output includes the comment with the other data, but if you don't use -D, the comment isn't included. dmd must figure if you aren't generating documentation, it can just discard all doc comments.

We'd probably want to change that if doing comment as a trait, because it would be mysterious if it didn't work sometimes.


BTW I wanted a traits(comment) over the weekend myself. I was asked to generate some metadata for one of my app apis in XML format and send it up to a third party service. I ended up just adding the needed docs by hand.

On Monday, 20 August 2012 at 23:28:54 UTC, Adam D. Ruppe wrote:
> http://dlang.org/ddoc.html
>
> dmd -D generates some html output based on comments.

That's a good point ... I've never messed with ddoc before, so I thought it was a different tool... but if all of that information is part of the D spec already, it probably would be a fairly simple addition.

On 8/20/12 6:41 PM, bearophile wrote:
> David:
>
>> So no official word to it?
>
> Why don't you write here a list of possible applications (use cases) of
> your idea?
>
> I hope Andrei will comment a little. It's a very simple additive change,
> and it looks useful.

Well it should be said there's no commitment, express or implied, from anyone's part to make timely comments. Also, simplicity of implementation (alleged or real) has a low priority when it comes to ranking.

That being said, just like the next guy I can cautiously say "this seems nice" upon a cursory look. But there are - even when restricting ourselves to ddoc - features of greater importance, such as adding unittests automatically to ddoc.


Andrei

Andrei Alexandrescu:

> Well it should be said there's no commitment, express or implied, from anyone's part to make timely comments.

Of course. Thank you for your answer.

Bye,
bearophile

On 19-08-2012 14:26, David wrote:
> I want to get the (ddoc)-comment of a certain function/member/struct …
> so I can generate help-messages at compiletime, without the need to
> duplicate the comments. Like pythons function.__doc__ or class.__doc__
> etc. is there anything planed for D, e.g. __traits(getComment, foo.bar)?
>
> If not what do you think of it, I would love this addition.

I implemented this somewhat trivially, so you can do:

/**
 * Magic.
 */
void foo() {}

pragma(msg, __traits(getDdoc, foo));

But one problem that quickly ruins the usefulness of this is that Ddoc comments are only gathered when -D is passed to DMD (and therefore D_Ddoc is defined).

One way to solve this problem is to always gather doc comments unconditionally. This is not optimal, however, because a lot of code is written with the assumption that doc comments should only be present when D_Ddoc is defined, so in many libraries you'll see code that goes like:

version (D_Ddoc)
{
    /**
     * Magic.
     */
    void foo();
}
else
{
    void foo()
    {
    }
}

So, I don't know. It seems like a mess to get working properly.

-- 
Alex Rønne Petersen
alex@lycus.org
http://lycus.org