www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - docs generation for mixins

reply 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
May 15 2016
next sibling parent 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.
May 15 2016
prev sibling parent 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 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
May 15 2016