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 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

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.

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

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

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

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