omni360 / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

Class-level functions such as goog.dom.getElement documentation never output #325

Closed GoogleCodeExporter closed 8 years ago

GoogleCodeExporter commented 8 years ago
This page for example:

http://closure-library.googlecode.com/svn/docs/namespace_goog_dom.html

should contain the docs of goog.dom.getElement(), but it doesn't, and in fact 
these docs are not rendered anywhere as far as I can tell. jsdoc toolkit does 
the same from the command line. So for documentation on these important methods 
and many others, one has to read the source javascript code manually, without 
formatting and links.

What steps will reproduce the problem?

1. java -jar jsrun.jar app/run.js -a -t=templates/jsdoc 
../closure-library/trunk/closure/goog/dom/dom.js
2. sensible-browser out/jsdoc/index.html
3. grep getElement out/jsdoc/index.html

What is the expected output? What do you see instead?

Expected documentation of goog.dom.getElement, but there was none.

What version of the product are you using? On what operating system?

2.4.0 on Linux (Ubuntu Maverick)

Please provide any additional information below.

Same issue applies to official Closure docs at 
http://closure-library.googlecode.com/svn/docs/namespace_goog_dom.html. Not 
sure whether these are generated using the same code.

Original issue reported on code.google.com by wil...@gmail.com on 15 Jul 2011 at 10:32

GoogleCodeExporter commented 8 years ago
This is entirely an issue with the template you are using, and you are 
encouraged to modify/create a new/better template that lists symbols like 
'goog.dom.foo' and 'goog.dom.bar' all on a single page if that is what you 
want. However, the default template for JSDoc Toolkit expects each level of the 
name to be documented separately, and will produce separate pages for each 
level. So, in this case, a namespace named "goog", another namespace named 
"dom" and a method named "foo" would yield three pages of documentation, one 
for each level of namespacing. For example:

/**
    @name goog
    @namespace
 */

/**
    @name goog.dom
    @namespace
 */

/**
    @name goog.dom.foo
    @function
 */

Aside from the way the HTML pages are organized, it seems that you are pointing 
out that the JSDoc used by Google is not 100% compatible with the JSDoc that 
JSDoc Toolkit prefers. To that I can only say that Google has decided to create 
their own dialect of JSDoc and did not consult anyone on this project or our 
mailing list when they did so. Which is perfectly fine by me, but it's a little 
unfair to then expect us to be compatible with whatever they eventually came up 
with.

Original comment by micmath on 15 Jul 2011 at 1:20