• ikod (20/20) May 15 2016 Hello,
• ag0aep6g (23/40) May 15 2016 Looks like doc generation doesn't expand mixins. I'm afraid there is no
• Jonathan M Davis via Digitalmars-d-learn (15/35) May 15 2016 AFAIK, ddoc doesn't work with string mixins. It _was_ fixed at some poin...

ikod <geller.garry gmail.com> writes:

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

ag0aep6g <anonymous example.com> writes:

On 05/15/2016 08:41 PM, ikod wrote:
 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.

Looks like doc generation doesn't expand mixins. I'm afraid there is no 
way to do this.

Some loosely related thoughts:

Instead of mixing in the whole declaration, generate the type (or 
function parameters, or whatever) with a template:
----
template V() { alias V = int; }

///
struct X {
     /// comment for y
     int y;
     /// comment for z
     V!() z;
}
----

Use a dummy declaration for doc generation:
----
     /// comment for z
     version (D_Ddoc) int z;
     else mixin(V("z"));
----

By the way, `-Dddocs` implies `-D`. You don't need both.

Jonathan M Davis via Digitalmars-d-learn writes:

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



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