www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 648] New: DDoc: unable to document mixin statement

reply d-bugmail puremagic.com writes:
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...


--
Dec 04 2006
next sibling parent d-bugmail puremagic.com writes:
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







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


--
May 06 2007
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648


Jonas Drewsen <jdrewsen gmail.com> changed:

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



---




 /// 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: -------
Jan 21 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648




---
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: -------
Jan 21 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648




---


 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: -------
Jan 21 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
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





 /// 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: -------
Jan 27 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648




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





 /// 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: -------
Jan 27 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
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



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: -------
Mar 17 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
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



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: -------
Jan 13 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648




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


Issue 648 - Expand template mixins in ddoc

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Jan 14 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648




Commit pushed to dmd-1.x at https://github.com/D-Programming-Language/dmd

https://github.com/D-Programming-Language/dmd/commit/00bc154aa5bbe3bbad72906edbfa6ab8caf0fc6a
fix Issue 648 - DDoc: unable to document mixin statement

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Jan 14 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648


Walter Bright <bugzilla digitalmars.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
                 CC|                            |bugzilla digitalmars.com
         Resolution|                            |FIXED



13:44:12 PST ---
The string mixin issue isn't fixed, but that is issue 2420.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Jan 14 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648


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

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |REOPENED
         Resolution|FIXED                       |



13:47:36 PST ---
It's not fixed.

The revert should have been done in full because of the uncaught bug, instead
you created your own fixup of my pull and now master is failing:
http://d.puremagic.com/test-results/

You should revert everything and allow me to work on the fix again.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Jan 14 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648




14:09:56 PST ---
reverted.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Jan 14 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648


Jacob Carlborg <doob me.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |doob me.com



I think this would be useful to have. For example:

/// doc
class Foo
{
    /// doc
    mixin Singleton;
}

In this case you might want that the singleton should be documented and part of
the public API. It would be a good idea to know that Foo is a singleton.

Another example:

/// doc
class Bar
{
    /// doc
    mixin Property!(int, "x");
}

The mixin would expand to something like:

private int x_;
 property int x () { return x_; }
 property int x (int value) { return x_ = value; }

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Jan 14 2013
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=648




10:56:05 PST ---
https://github.com/D-Programming-Language/dmd/pull/1485

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