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

[Rikki Cattermole via Digitalmars-d]

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