• Gerald Stocker (11/11) May 06 2007 Hello,
• Kirk McDonald (9/25) May 06 2007 The doc-comment needs to come immediately /before/ the delcaration. Have...
• Gerald Stocker (7/24) May 06 2007 Nope, that doesn't work either. I wonder if I should report this as a bu...
• Ary Manzana (9/25) May 06 2007 I already asked for this:
• Gerald Stocker (6/18) May 06 2007 Well, what I've been doing is trying to put as much information as is
• Gregor Richards (4/20) May 06 2007 I can't offer you a reason, but I can offer you an explanation: mixins
• Ary Manzana (11/15) May 06 2007 Yes. I'm seeing in the front-end code that the following happens:

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

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

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.

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

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

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

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