August 20, 2012 Re: trait for (ddoc)-comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to David | 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
|
August 20, 2012 Re: trait for (ddoc)-comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to 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 |
August 20, 2012 Re: trait for (ddoc)-comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Chris Cain | 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. |
August 20, 2012 Re: trait for (ddoc)-comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Adam D. Ruppe | 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.
|
August 21, 2012 Re: trait for (ddoc)-comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to bearophile | 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
|
August 21, 2012 Re: trait for (ddoc)-comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to Andrei Alexandrescu | 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
|
August 21, 2012 Re: trait for (ddoc)-comments | ||||
---|---|---|---|---|
| ||||
Posted in reply to David | 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 |
Copyright © 1999-2021 by the D Language Foundation