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

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

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

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.

This is now a pull request:
https://github.com/D-Programming-Language/dmd/pull/3531

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