www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - A new trait to retrieve doc comments (if available).

reply "Mason McGill" <mmcgill caltech.edu> writes:
**I'm fairly new to D, so let me know if this belongs in another 
thread.**

I'd like to contribute a new feature to the DMD front-end, and 
I'd appreciate some feedback on the design before I start on a 
pull request.

Feature:
========
`__traits(comment, symbol)` will evaluate to the doc-comment of 
`symbol`, if it is available, and "", otherwise. For DMD, this 
means it will provide comment information if the "-D" compiler 
option is used. Other implementations can choose to always 
evaluate it to "".

Use Cases:
==========
Here's my use case: I'm building an automatic wrapper generator 
for binding D to dynamic languages (mostly for scientific 
applications, at the moment). It's like SWIG, but more automated 
and narrower in scope.  Right now, I have two suboptimal options 
for supporting documentation comments:

1) Have users put their documentation in UDAs (instead of 
comments), and extract those.  This means departing from D style 
guidelines, and that DDOC doesn't work.

2) Dig comments out of DMD's JSON output.  This means users have 
to inform the wrapping tool of all of their D source files (not 
just a shared library), complicating build setups.  It also means 
DMD loads and parses each file twice.

Having doc-comments accessible at compile time would let me 
simplify the wrapping process for my users.

Other applications include metaprogramming (e.g. forwarding 
documentation from a template argument) and simplifying 
documentation generators. I'm sure having doc-comments accessible 
in Python made things like Sphinx and IPython easier to build.

Implementation:
===============
I'm not too familiar with DMD, but it seems like evaluating 
`__traits(comment, symbol)` would just require reading out the 
relevant `DSymbol`'s `comment` field.

Alternatives:
=============
Alternative names:
- `__traits(getComment, symbol)`
- `__traits(documentation, symbol)`
- `__traits(getDocumentation, symbol)`

Alternative behaviors:
- `__traits(comment, symbol)` could evaluate to `null` (rather 
than "") if there is no comment associated with `symbol`.

Thoughts?
May 05 2014
next sibling parent Jacob Carlborg <doob me.com> writes:
On 06/05/14 02:49, Mason McGill wrote:

 **I'm fairly new to D, so let me know if this belongs in another thread.**

 I'd like to contribute a new feature to the DMD front-end, and I'd
 appreciate some feedback on the design before I start on a pull request.

 Feature:
 ========
 `__traits(comment, symbol)` will evaluate to the doc-comment of
 `symbol`, if it is available, and "", otherwise. For DMD, this means it
 will provide comment information if the "-D" compiler option is used.
 Other implementations can choose to always evaluate it to "".

 Use Cases:
 ==========
 Here's my use case: I'm building an automatic wrapper generator for
 binding D to dynamic languages (mostly for scientific applications, at
 the moment). It's like SWIG, but more automated and narrower in scope.
 Right now, I have two suboptimal options for supporting documentation
 comments:


I have thought about it a couple of times before. I would say, just go 
for it. __traits is a pretty good staring point for someone not familiar 
with the DMD source.

-- 
/Jacob Carlborg
May 05 2014
prev sibling next sibling parent reply "bearophile" <bearophileHUGS lycos.com> writes:
Mason McGill:


 Other implementations can choose to always evaluate it to "".


Other implementations have to give the ddostring as well.

In D modules too have a ddoc string.

Regarding comments on single variables, like this, I think they 
can be ignored for the moment, and added later with the same API 
if needed:

int foo = 5; /// Not a string.

Bye,
bearophile
May 06 2014
parent reply "Mason McGill" <mmcgill caltech.edu> writes:
Thanks for the feedback!

On Tuesday, 6 May 2014 at 07:41:20 UTC, bearophile wrote:

 Mason McGill:


 Other implementations can choose to always evaluate it to "".


 Other implementations have to give the ddostring as well.


Good to know! This will simplify the entry in the "Traits" 
documentation page.


 In D modules too have a ddoc string.

 Regarding comments on single variables, like this, I think they 
 can be ignored for the moment, and added later with the same 
 API if needed:

 int foo = 5; /// Not a string.


It appears DMD already extracts module and variable comments.  
The JSON output for the following code associates all 3 comments 
with the appropriate symbols (compiled with "dmd -D -X -o- 
test.d").

     /**
      * This is the test module.
      */
     module test;

     const x = 5; /// This is x.

     /**
      * This is the main function.
      */
     void main() {}

So, it seems `__traits(comment, symbol)` should work for any 
symbol, at least the way I plan to implement it. This seems like 
the most useful behavior.
May 06 2014
parent "Mason McGill" <mmcgill caltech.edu> writes:
This is now a pull request:
https://github.com/D-Programming-Language/dmd/pull/3531
May 06 2014
prev sibling parent Rikki Cattermole <alphaglosined gmail.com> writes:
On 6/05/2014 12:49 p.m., Mason McGill wrote:

 **I'm fairly new to D, so let me know if this belongs in another thread.**

 I'd like to contribute a new feature to the DMD front-end, and I'd
 appreciate some feedback on the design before I start on a pull request.

 Feature:
 ========
 `__traits(comment, symbol)` will evaluate to the doc-comment of
 `symbol`, if it is available, and "", otherwise. For DMD, this means it
 will provide comment information if the "-D" compiler option is used.
 Other implementations can choose to always evaluate it to "".

 Use Cases:
 ==========
 Here's my use case: I'm building an automatic wrapper generator for
 binding D to dynamic languages (mostly for scientific applications, at
 the moment). It's like SWIG, but more automated and narrower in scope.
 Right now, I have two suboptimal options for supporting documentation
 comments:

 1) Have users put their documentation in UDAs (instead of comments), and
 extract those.  This means departing from D style guidelines, and that
 DDOC doesn't work.

 2) Dig comments out of DMD's JSON output.  This means users have to
 inform the wrapping tool of all of their D source files (not just a
 shared library), complicating build setups.  It also means DMD loads and
 parses each file twice.

 Having doc-comments accessible at compile time would let me simplify the
 wrapping process for my users.

 Other applications include metaprogramming (e.g. forwarding
 documentation from a template argument) and simplifying documentation
 generators. I'm sure having doc-comments accessible in Python made
 things like Sphinx and IPython easier to build.

 Implementation:
 ===============
 I'm not too familiar with DMD, but it seems like evaluating
 `__traits(comment, symbol)` would just require reading out the relevant
 `DSymbol`'s `comment` field.

 Alternatives:
 =============
 Alternative names:
 - `__traits(getComment, symbol)`
 - `__traits(documentation, symbol)`
 - `__traits(getDocumentation, symbol)`

 Alternative behaviors:
 - `__traits(comment, symbol)` could evaluate to `null` (rather than "")
 if there is no comment associated with `symbol`.

 Thoughts?


I'm going to be (rather soon) having a play with generating PlantUML[0] 
descriptors and getting Cmsed to automatically create the diagrams from 
them.
So I'm already feeling the need to get comments for symbols!

Now if only I can have some way to get all statements, expressions ext. 
in the code.. that would be awesome (sequence diagrams).

[0] http://plantuml.sourceforge.net/classes.html
May 14 2014