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
