[Issue 648] DDoc: unable to document mixin statement

[d-bugmail at puremagic.com]

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


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

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


--- Comment #5 from Marco Leise <Marco.Leise at 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: -------