Object nesting in class menu
James Coglan
pages for all declared classes, even if their parent objects are
missing e.g. this:
/** section: ajax
* class Ajax.Some.RandomClass
**/
Will generate a documentation page at ajax/ajax/some/randomclass.html,
even if Ajax and Ajax.Some are not documented anywhere.
I just wanted to know whether anyone's really attached to the nested
list used for the object menu in the templates. Personally I don't
think the nesting is useful (well, one level is fine for grouping
classes into sections) and it means that classes such as the above
can't be listed unless their containing namespace is declared. I've
run into a bunch of situations writing libraries where everything
lives in a namespace object and I don't want to document the namespace
object because it has no useful methods or anything else worth
mentioning.
Any thoughts?
PS. In Firefox 3 the menu disappears if I mouseover it by moving my
mouse up from below it. Moving the mouse down from above the menu
keeps it open -- anyone else getting this?
Tobie Langel
> pages for all declared classes, even if their parent objects are
> missing e.g. this:
>
> /** section: ajax
> * class Ajax.Some.RandomClass
> **/
>
> Will generate a documentation page at ajax/ajax/some/randomclass.html,
> even if Ajax and Ajax.Some are not documented anywhere.
Awesome. Thank you.
> I just wanted to know whether anyone's really attached to the nested
> list used for the object menu in the templates. Personally I don't
> think the nesting is useful (well, one level is fine for grouping
> classes into sections) and it means that classes such as the above
> can't be listed unless their containing namespace is declared. I've
> run into a bunch of situations writing libraries where everything
> lives in a namespace object and I don't want to document the namespace
> object because it has no useful methods or anything else worth
> mentioning.
>
> Any thoughts?
Have a look at Andrew's implementation for Prototype (on Github).
James Coglan
Have a look at Andrew's implementation for Prototype (on Github).
Where abouts? Had a quick poke around under savetheclocktower and couldn't find it (sorry, I'm probably being dense).
Tobie Langel
Sent from my mobile phone.
James Coglan
It's under sstephenson
Sent from my mobile phone.
On Mar 17, 2009, at 16:07, James Coglan <jco...@googlemail.com> wrote:
> Have a look at Andrew's implementation for Prototype (on Github).
Right, cool. Any objections to me doing something similar for the default templates, or would you rather keep the nested version? It does make a good example of the PDoc data model and I imagine people will be making their own templates anyway. My only concern is that it could be potentially confusing, I certainly had a few failed attempts when I first started using PDoc because I didn't know it was walking a tree rather than just listing everything I'd documented.
Tobie Langel
Basically, the template included with PDoc should be customizable
enough (easy branding, simple color theme, automatic inclusion of
README file for index page, etc.) that users don't need to make their
own.
Andrew was planning on back-porting his custom Prototype template to
PDoc, maybe you want to discuss it directly with him (ideally through
the mailing list so that w can all benefit).