http://d.puremagic.com/issues/show_bug.cgi?id=648

           Summary: DDoc: unable to document mixin statement
           Product: D
           Version: 0.176
          Platform: PC
        OS/Version: Windows
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DMD
        AssignedTo: bugzilla@digitalmars.com
        ReportedBy: tomas@famolsen.dk


/// this is a class
class A
{
/// This mixin will bla bla bla
mixin MyMixin!();
}

this will only generate docs for the class. not the mixin.
Some will probably consider this a feature request, but I'd call it a bug...


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=648


gobstocker@gmail.com changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         OS/Version|Windows                     |All
            Version|0.176                       |1.014




------- Comment #1 from gobstocker@gmail.com  2007-05-06 23:12 -------
(In reply to comment #0)
> /// this is a class
> class A
> {
> /// This mixin will bla bla bla
> mixin MyMixin!();
> }
> 
> this will only generate docs for the class. not the mixin.
> Some will probably consider this a feature request, but I'd call it a bug...
> 

The same occurs with mixin declarations (DMD 1.014 on linux):

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

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

And docs are not generated for foo or bar.

Gregor Richards pointed out in news://news.digitalmars.com:119/f1m3u7$26g8$1@digitalmars.com that mixins are parsed much later than ddoc comments.

But I would also consider this a bug.


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=648


Jonas Drewsen <jdrewsen@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jdrewsen@gmail.com


--- Comment #2 from Jonas Drewsen <jdrewsen@gmail.com> 2012-01-21 11:50:17 PST ---
(In reply to comment #1)
> (In reply to comment #0)
> > /// this is a class
> > class A
> > {
> > /// This mixin will bla bla bla
> > mixin MyMixin!();
> > }
> > 
> > this will only generate docs for the class. not the mixin.
> > Some will probably consider this a feature request, but I'd call it a bug...
> > 
> 
> The same occurs with mixin declarations (DMD 1.014 on linux):
> 
> /// Documentation for foo.
> mixin("int foo;");
> 
> mixin("int foo; /// Documentation for foo.");
> 
> And docs are not generated for foo or bar.
> 
> Gregor Richards pointed out in news://news.digitalmars.com:119/f1m3u7$26g8$1@digitalmars.com that mixins are parsed much later than ddoc comments.
> 
> But I would also consider this a bug.

Comment 1 is a duplicate of bug 2420

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=648



--- Comment #3 from Jonas Drewsen <jdrewsen@gmail.com> 2012-01-21 14:18:42 PST ---
https://github.com/D-Programming-Language/dmd/pull/634

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=648



--- Comment #4 from Jonas Drewsen <jdrewsen@gmail.com> 2012-01-21 14:35:04 PST ---
(In reply to comment #3)
> https://github.com/D-Programming-Language/dmd/pull/634

Actually does not fix this bug but another mixin related bug related to documentation.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=648


Marco Leise <Marco.Leise@gmx.de> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |Marco.Leise@gmx.de


--- Comment #5 from Marco Leise <Marco.Leise@gmx.de> 2012-01-27 05:12:41 PST ---
(In reply to comment #0)
> /// this is a class
> class A
> {
> /// This mixin will bla bla bla
> mixin MyMixin!();
> }
> 
> this will only generate docs for the class. not the mixin.
> Some will probably consider this a feature request, but I'd call it a bug...

I would call it a feature request, because for it to be a bug, there would have to be a clear definition how this should work or a similar case that can act as a template. DDoc documents 'classes', 'structs', 'methods', ... in other words named symbols. "mixin MyMixin;" isn't a symbol and usually not interesting for the user of the class. And private members aren't documented, because they aren't usable by the target audience of API docs. So I assume your mixin does not itself add public symbols that should be documented ? Or do you request a feature to go beyond API documentation with DDOC, and also document how a mixin is expanded in the class ? That's what normal comments are for!

Maybe you can elaborate a bit on what the mixin does and why it is necessary to document the 'unexpanded' thing ? I would say yes, if you proposed to move DDOC generation after mixin expansion (so newly introduced methods can be documented), but then you could document them inside the mixin itself - which would be a different 'bug'. Remember that a single mixin can add any number of new symbols, so documentation above "mixin ..." may come short in many situations. You can also discuss this on the D newsgroup, but be sure to give a strong argument (real example code) for this feature.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=648



--- Comment #6 from Tomas Lindquist Olsen <tomas@famolsen.dk> 2012-01-27 05:45:44 PST ---
It's been five years. TBH I don't really care anymore. Close this issue up if you will, I've moved on ...

(In reply to comment #5)
> (In reply to comment #0)
> > /// this is a class
> > class A
> > {
> > /// This mixin will bla bla bla
> > mixin MyMixin!();
> > }
> > 
> > this will only generate docs for the class. not the mixin.
> > Some will probably consider this a feature request, but I'd call it a bug...
> 
> I would call it a feature request, because for it to be a bug, there would have to be a clear definition how this should work or a similar case that can act as a template. DDoc documents 'classes', 'structs', 'methods', ... in other words named symbols. "mixin MyMixin;" isn't a symbol and usually not interesting for the user of the class. And private members aren't documented, because they aren't usable by the target audience of API docs. So I assume your mixin does not itself add public symbols that should be documented ? Or do you request a feature to go beyond API documentation with DDOC, and also document how a mixin is expanded in the class ? That's what normal comments are for!
> 
> Maybe you can elaborate a bit on what the mixin does and why it is necessary to document the 'unexpanded' thing ? I would say yes, if you proposed to move DDOC generation after mixin expansion (so newly introduced methods can be documented), but then you could document them inside the mixin itself - which would be a different 'bug'. Remember that a single mixin can add any number of new symbols, so documentation above "mixin ..." may come short in many situations. You can also discuss this on the D newsgroup, but be sure to give a strong argument (real example code) for this feature.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=648


Raphael Londeix <raphael.londeix@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |raphael.londeix@gmail.com


--- Comment #7 from Raphael Londeix <raphael.londeix@gmail.com> 2012-03-17 11:08:55 PDT ---
Hi,

I would say that document mixins themselves is not really useful (like Marco Leise said, the targeted audience of the generated documentation). However, since the compiler generates documentation (which is an awesome fact btw), it could also generate doc for generated source code from mixins.

When the generated code goes on a public scope, having it documented is not only useful, it is necessary. For example, I use mixin to generate some callbacks accordingly of a network protocol definition. Since the protocol is known at compile time (and fully documented), these callbacks should be documented as well.

Feature or bug, I don't know, but it's not working with dmd v2.058 :)

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=648


Andrej Mitrovic <andrej.mitrovich@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |pull
                 CC|                            |andrej.mitrovich@gmail.com
           Platform|x86                         |All
            Version|1.014                       |D1 & D2
         AssignedTo|bugzilla@digitalmars.com    |andrej.mitrovich@gmail.com


--- Comment #8 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2013-01-13 12:50:59 PST ---
https://github.com/D-Programming-Language/dmd/pull/1480

This only implements template mixin statements in D2, and not string mixins.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=648



--- Comment #9 from github-bugzilla@puremagic.com 2013-01-14 11:56:55 PST ---
Commits pushed to master at https://github.com/D-Programming-Language/dmd

https://github.com/D-Programming-Language/dmd/commit/a671cb3480d68201e868adf5f103fff95574a597 Fixes Issue 648 - Expand template mixins in ddoc.

https://github.com/D-Programming-Language/dmd/commit/33c36716ed97b67e454815565c6f21f41af51983 Merge pull request #1480 from AndrejMitrovic/Fix648

Issue 648 - Expand template mixins in ddoc

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------