www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - DDoc and mixins

reply Gerald Stocker <gobstocker gmail.com> writes:
Hello,

Is there any way to attach a documentation comment to declarations that 
are generated by mixins? Neither of the following work:

/// Documentation for foo.
mixin("int foo;");

mixin("int foo; /// Documentation for foo.");

I am working on a 6502 emulator in D which relies heavily on CTFE + 
mixins to generate methods for each of the 6502's opcodes. The code is 
heavily commented with details of 6502 behavior, and I'd like to be able 
to include those comments in the generated ddoc documentation.

--Gerald
May 06 2007
next sibling parent reply Kirk McDonald <kirklin.mcdonald gmail.com> writes:
Gerald Stocker wrote:
 Hello,
 
 Is there any way to attach a documentation comment to declarations that 
 are generated by mixins? Neither of the following work:
 
 /// Documentation for foo.
 mixin("int foo;");
 
 mixin("int foo; /// Documentation for foo.");
 

The doc-comment needs to come immediately /before/ the delcaration. Have you tried: mixin("/** Documentation for foo. */ int foo;");
 I am working on a 6502 emulator in D which relies heavily on CTFE + 
 mixins to generate methods for each of the 6502's opcodes. The code is 
 heavily commented with details of 6502 behavior, and I'd like to be able 
 to include those comments in the generated ddoc documentation.
 
 --Gerald

-- Kirk McDonald http://kirkmcdonald.blogspot.com Pyd: Connecting D and Python http://pyd.dsource.org
May 06 2007
parent Gerald Stocker <gobstocker gmail.com> writes:
Kirk McDonald wrote:
 Gerald Stocker wrote:
 Hello,

 Is there any way to attach a documentation comment to declarations 
 that are generated by mixins? Neither of the following work:

 /// Documentation for foo.
 mixin("int foo;");

 mixin("int foo; /// Documentation for foo.");

The doc-comment needs to come immediately /before/ the delcaration. Have you tried: mixin("/** Documentation for foo. */ int foo;");

Nope, that doesn't work either. I wonder if I should report this as a bug? (Also, doc comments to the right of a declaration are OK according to the D language spec. int foo; /// Documentation for foo. works fine if it is not a mixin but just typed directly in the source.) --Gerald.
May 06 2007
prev sibling next sibling parent reply Ary Manzana <ary esperanto.org.ar> writes:
I already asked for this:

news://news.digitalmars.com:119/erib78$g6c$1 digitalmars.com

with no answer. :-(

Maybe some think that if the code is generated by a mixin, than it is 
trivial or easy to understand, because it follows a pattern (for 
example, properties). However if a lot of classes are to be generated 
this way, and they'll be part of some library, then you'd really like 
them to have comments.

Gerald Stocker escribió:
 Hello,
 
 Is there any way to attach a documentation comment to declarations that 
 are generated by mixins? Neither of the following work:
 
 /// Documentation for foo.
 mixin("int foo;");
 
 mixin("int foo; /// Documentation for foo.");
 
 I am working on a 6502 emulator in D which relies heavily on CTFE + 
 mixins to generate methods for each of the 6502's opcodes. The code is 
 heavily commented with details of 6502 behavior, and I'd like to be able 
 to include those comments in the generated ddoc documentation.
 
 --Gerald

May 06 2007
parent Gerald Stocker <gobstocker gmail.com> writes:
Ary Manzana wrote:
 I already asked for this:
 
 news://news.digitalmars.com:119/erib78$g6c$1 digitalmars.com
 
 with no answer. :-(
 
 Maybe some think that if the code is generated by a mixin, than it is 
 trivial or easy to understand, because it follows a pattern (for 
 example, properties). However if a lot of classes are to be generated 
 this way, and they'll be part of some library, then you'd really like 
 them to have comments.
 

Well, what I've been doing is trying to put as much information as is reasonable in the doc comments for the compile-time functions which generate the mixin strings. It's not too unworkable, but sometimes the information ends up in a different order than I would like. --Gerald
May 06 2007
prev sibling parent reply Gregor Richards <Richards codu.org> writes:
Gerald Stocker wrote:
 Hello,
 
 Is there any way to attach a documentation comment to declarations that 
 are generated by mixins? Neither of the following work:
 
 /// Documentation for foo.
 mixin("int foo;");
 
 mixin("int foo; /// Documentation for foo.");
 
 I am working on a 6502 emulator in D which relies heavily on CTFE + 
 mixins to generate methods for each of the 6502's opcodes. The code is 
 heavily commented with details of 6502 behavior, and I'd like to be able 
 to include those comments in the generated ddoc documentation.
 
 --Gerald

I can't offer you a reason, but I can offer you an explanation: mixins are expanded far later in parsing than ddoc comments are parsed. - Gregor Richards
May 06 2007
parent Ary Manzana <ary esperanto.org.ar> writes:
Yes. I'm seeing in the front-end code that the following happens:

1. The modules are parsed.
2. Documentation is generated.
3. DI files are generated.
4. Semantic analysis is done.
5. Code is generated.

Maybe step 2 could be moved after step 4... and, of course, the 
documentation read by the mixins (they are read, since they are read 
using the same Parser class) should be sent back to the main body... or 
kept someway.

Gregor Richards escribió:
 I can't offer you a reason, but I can offer you an explanation: mixins 
 are expanded far later in parsing than ddoc comments are parsed.
 
  - Gregor Richards

May 06 2007