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.
David: > 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. +1 Yeah!Bye, bearophile
David: > 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. I am sure there are MANY other possible applications for such a trait. Compile-time doctests maybe are a bit too much (but they are OK for compile-time functions!), but things like this become possible: http://pypi.python.org/pypi/docopt/0.1 Bye, bearophile
Am 19.08.2012 15:30, schrieb bearophile: > David: > >> 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. > > I am sure there are MANY other possible applications for such a trait. > Compile-time doctests maybe are a bit too much (but they are OK for > compile-time functions!), but things like this become possible: > http://pypi.python.org/pypi/docopt/0.1 > > Bye, > bearophile Actually, that's why I want that trait :)
David: > Actually, that's why I want that trait :) But in practice, as your command line programs get a little more complex, docopt is not enough, you need normal programming with things like argparse. So maybe a mix of the two ideas is better, to write most stuff in the docstring, and then refine its semantics below with normal code. Bye, bearophile
Am 19.08.2012 16:36, schrieb bearophile:
> David:
>
>> Actually, that's why I want that trait :)
>
> But in practice, as your command line programs get a little more
> complex, docopt is not enough, you need normal programming with things
> like argparse.
>
> So maybe a mix of the two ideas is better, to write most stuff in the
> docstring, and then refine its semantics below with normal code.
>
> Bye,
> bearophile
I am not writing an actual argparsing-library, I thought of starting
one, but then I realized, I don't have the time to do something amazing
like argparse, so I decided to go with a less complex and heavily CTFE'd
version. It looks like that:
struct AppArguments {
string username;
Alias!("username") u;
string password;
Alias!("password") p;
bool credentials;
Alias!("credentials") c;
(Continue reading)
On 19-Aug-12 18:45, David wrote:
> Am 19.08.2012 16:36, schrieb bearophile:
>> David:
>>
>>> Actually, that's why I want that trait :)
>>
>> But in practice, as your command line programs get a little more
>> complex, docopt is not enough, you need normal programming with things
>> like argparse.
>>
>> So maybe a mix of the two ideas is better, to write most stuff in the
>> docstring, and then refine its semantics below with normal code.
>>
>> Bye,
>> bearophile
>
> I am not writing an actual argparsing-library, I thought of starting
> one, but then I realized, I don't have the time to do something amazing
> like argparse, so I decided to go with a less complex and heavily CTFE'd
> version. It looks like that:
>
> struct AppArguments {
> string username;
> Alias!("username") u;
>
> string password;
> Alias!("password") p;
>
> bool credentials;
> Alias!("credentials") c;
(Continue reading)
Am Sun, 19 Aug 2012 15:30:33 +0200 schrieb "bearophile" <bearophileHUGS <at> lycos.com>: > David: > > > 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. > > I am sure there are MANY other possible applications for such a > trait. Compile-time doctests maybe are a bit too much (but they > are OK for compile-time functions!), but things like this become > possible: > http://pypi.python.org/pypi/docopt/0.1 > > Bye, > bearophile Jesus! Did Nick write docopt? It's full of swear words. Hmm, no, Vladimir Keleshev. It sounds nice, I would see the common Python way of parsing options a big step forward already. E.g. including help texts and printing the usage info to stdout. -- -- Marco
Am 19.08.2012 14:26, schrieb David: > 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. So no official word to it?
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
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.
(Continue reading)
RSS Feed