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
next sibling 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 "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
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 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.


=20
 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
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
next sibling parent reply "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
parent reply "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
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 reply 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
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