[Issue 648] DDoc: unable to document mixin statement

[d-bugmail at puremagic.com]

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



--- Comment #6 from Tomas Lindquist Olsen <tomas at 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: -------