Structuring documentation
115 views
Skip to first unread message
Jens Müller
May 22, 2012, 9:00:04 AM5/22/12
to JSDoc Users
Hi all,
I am generating JavaScript documentation using jsdoc-toolkit[1]. I
have several "classes" marked with @class that only exist as
documentation, but not as code. The reason for this is that they
describe the structure of data that is loaded from a server as JSON.
This results in quite a number of "classes", which I up to now have
marked by using a common prefix. Nevertheless, the list of types in
the generated documentation becomes considerably longer because of
them. Is there a possibility to structure the documentation somehow,
using some kind of packages or namespaces? Possibly there is a
documentation generator that can do this and is mostly compatible to
the documentation tags used by jsdoc-toolkit?
Thanks a lot!
Cheers,
Jens
[1] http://code.google.com/p/jsdoc-toolkit/
I am generating JavaScript documentation using jsdoc-toolkit[1]. I
have several "classes" marked with @class that only exist as
documentation, but not as code. The reason for this is that they
describe the structure of data that is loaded from a server as JSON.
This results in quite a number of "classes", which I up to now have
marked by using a common prefix. Nevertheless, the list of types in
the generated documentation becomes considerably longer because of
them. Is there a possibility to structure the documentation somehow,
using some kind of packages or namespaces? Possibly there is a
documentation generator that can do this and is mostly compatible to
the documentation tags used by jsdoc-toolkit?
Thanks a lot!
Cheers,
Jens
[1] http://code.google.com/p/jsdoc-toolkit/
Michael Mathews
May 22, 2012, 10:18:36 AM5/22/12
to Jens Müller, JSDoc Users
http://code.google.com/p/jsdoc-toolkit/wiki/TagNamespace
Like
/**
* @name ext
* @namespace
*/
/**
* @name ext.KillCoptor9000
* @class
*/
etc
Michael Mathews
mic...@gmail.com
> --
> You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
> To post to this group, send email to jsdoc...@googlegroups.com.
> To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/jsdoc-users?hl=en.
>
Like
/**
* @name ext
* @namespace
*/
/**
* @name ext.KillCoptor9000
* @class
*/
etc
Michael Mathews
mic...@gmail.com
> You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
> To post to this group, send email to jsdoc...@googlegroups.com.
> To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/jsdoc-users?hl=en.
>
Jens Müller
May 22, 2012, 4:05:57 PM5/22/12
to JSDoc Users
On May 22, 4:18 pm, Michael Mathews <micm...@gmail.com> wrote:
> http://code.google.com/p/jsdoc-toolkit/wiki/TagNamespace
>
> Like
>
> /**
> * @name ext
> * @namespace
> */
>
> /**
> * @name ext.KillCoptor9000
> * @class
> */
>
> etc
>
list ... And the page of the ext namespace does not give a list of the
ext.* entries. Any ways to change this?
-- Jens
Michael Mathews
May 22, 2012, 5:55:58 PM5/22/12
to Jens Müller, JSDoc Users
Hi Jens,
Via JSDoc Toolkit's default template, all classes always appear in the top level class index, regardless of whether or not those classes are namespaced. You can edit the template you are using so it doesn't do that if it's important, but there isn't a tag you can add to change the template. There are alternative templates available too, maybe someone on the mailing list has a suggestion?
If you're interested in trying JSDoc 3, I just tried the same source code, and the default template generated output that still listed every class in a top-level index, but the page for the namespace did include links to all the classes within it.
Michael Mathews
mic...@gmail.com
Via JSDoc Toolkit's default template, all classes always appear in the top level class index, regardless of whether or not those classes are namespaced. You can edit the template you are using so it doesn't do that if it's important, but there isn't a tag you can add to change the template. There are alternative templates available too, maybe someone on the mailing list has a suggestion?
If you're interested in trying JSDoc 3, I just tried the same source code, and the default template generated output that still listed every class in a top-level index, but the page for the namespace did include links to all the classes within it.
Michael Mathews
mic...@gmail.com
Reply all
Reply to author
Forward
0 new messages