docs generation for mixins

[Jonathan M Davis via Digitalmars-d-learn]

On Sunday, May 15, 2016 18:41:26 ikod via Digitalmars-d-learn wrote:
> Hello,
>
> sorry if this question was asked before...
>
> How can I get docs generated for int z?
>
> -----
> string V(string var) {
>      return "int " ~ var ~ ";";
> }
> ///
> struct X {
>      /// comment for y
>      int y;
>      /// comment for z
>      mixin(V("z"));
> }
>
> void main()
> {
> }
> -----
>
> "dmd -D -Dddocs" generate docs for "y" only.
>
> Thanks

AFAIK, ddoc doesn't work with string mixins. It _was_ fixed at some point so
that it works for template mixins, but as I understand it, the documentation
itself then goes on the symbol in the template, and then you need to put an
empty ddoc comment on the mixin itself to make the documentation that was in
the template itself show up. An example of this would be

http://dlang.org/phobos/std_exception.html#.basicExceptionCtors

It _might_ be the case that if you put the ddoc comment inside of the string
mixin that it will then end up in the documentation, but I doubt it. AFAIK,
the fact that it works with template mixins is recent, though given that you
need to document both the symbol inside of the template and the point where
it's mixed in, I suppose that it could just be that it's worked for a while,
but no one knew how to actually use it in a way that worked. I've never
heard of documentation working with string mixins though.

- Jonathan M Davis