www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - trait for (ddoc)-comments

reply David <d dav1d.de> writes:
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.
Aug 19 2012
next sibling parent "bearophile" <bearophileHUGS lycos.com> writes:
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
Aug 19 2012
prev sibling next sibling parent reply "bearophile" <bearophileHUGS lycos.com> writes:
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
Aug 19 2012
parent reply David <d dav1d.de> writes:
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 :)
Aug 19 2012
parent reply David <d dav1d.de> writes:
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; uint width = 1024; uint height = 800; string host; Alias!("host") h; ushort port = 25565; bool no_snoop = false; } void main() { auto args = get_options!AppArguments(); } I added a default --help function to it, if there is no "help" member declared in AppArguments, but I realized ... --help without messages is kinda pointless ...
Aug 19 2012
parent reply Dmitry Olshansky <dmitry.olsh gmail.com> writes:
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; uint width = 1024; uint height = 800; string host; Alias!("host") h; ushort port = 25565; bool no_snoop = false; } void main() { auto args = get_options!AppArguments(); } I added a default --help function to it, if there is no "help" member declared in AppArguments, but I realized ... --help without messages is kinda pointless ...

What's wrong with std.getopt? I thought there was some movement to improve it (including auto-generating usage messages). -- Olshansky Dmitry
Aug 19 2012
parent David <d dav1d.de> writes:
 What's wrong with std.getopt? I thought there was some movement to
 improve it (including auto-generating usage messages).

It uses std.getopt for parsing.
Aug 19 2012
prev sibling next sibling parent "bearophile" <bearophileHUGS lycos.com> writes:
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
Aug 19 2012
prev sibling next sibling parent Marco Leise <Marco.Leise gmx.de> writes:
Am Sun, 19 Aug 2012 15:30:33 +0200
schrieb "bearophile" <bearophileHUGS lycos.com>:

 David:
=20
 I want to get the (ddoc)-comment of a certain=20
 function/member/struct =E2=80=A6 so I can generate help-messages at=20
 compiletime, without the need to duplicate the comments.

I am sure there are MANY other possible applications for such a=20 trait. Compile-time doctests maybe are a bit too much (but they=20 are OK for compile-time functions!), but things like this become=20 possible: http://pypi.python.org/pypi/docopt/0.1 =20 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. --=20 Marco
Aug 19 2012
prev sibling next sibling parent reply David <d dav1d.de> writes:
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?
Aug 20 2012
next sibling parent reply "bearophile" <bearophileHUGS lycos.com> writes:
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
Aug 20 2012
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Aug 20 2012
prev sibling next sibling parent "Chris Cain" <clcain uncg.edu> writes:
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
Aug 20 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
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.
Aug 20 2012
prev sibling next sibling parent "Chris Cain" <clcain uncg.edu> writes:
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.
Aug 20 2012
prev sibling parent "bearophile" <bearophileHUGS lycos.com> writes:
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
Aug 20 2012
prev sibling parent =?UTF-8?B?QWxleCBSw7hubmUgUGV0ZXJzZW4=?= <alex lycus.org> writes:
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
Aug 20 2012