**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?
