Marvin Humphrey wrote on 12/2/14, 5:59 PM:
On Tue, Dec 2, 2014 at 3:43 PM, Nick Wellnhofer<[email protected]> wrote:
On 02/12/2014 23:08, Marvin Humphrey wrote:
I'd suggest including complete documentation only when a DocuComment
appears in the .cfh source file. For subroutines, that will generally mean
only novel methods and inert functions, but it's conceievable that an
inherited method could provide a DocuComment explaining something about its
implementation.
For public methods whose interfaces are established in superclasses, I
suggest linking only.
I disagree. Especially for casual users, I think it's helpful to show all
the methods that a class implements. Otherwise, you miss many methods or you
end up permanently switching between the documentation of the class and one
or two of its superclasses. I'd only make an exception for Clownfish::Obj.
Well, I don't think our disagreement is that serious. I meant a link for each
method, not a link for each ancestor class -- so it's not that I'm opposed to
having inherited methods shown at all. (Thinking a little harder, my
preference would be to follow the conventions of the host language community.)
I like the idea of method docs (links at minimum) in every subclass
documentation. One of things about my own documentation that I dislike is having
to reference multiple pieces of documentation in order to get a complete sense
of the API for a given class. If that consolidation were automated, it would be
great for users, imo.
--
Peter Karman . http://peknet.com/ . [email protected]
