15

I'm looking for a tool to generate the documentation for JavaScript functions and properties even if there are no appropriately formatted comment blocks associated with those functions or properties (like Doxygen does).

This comparison between JSDoc and some other documenting tools mentions that JSDoc can parse the source code to generate documentation even if there is no comment blocks (something like Doxygen, as I mentioned above). They say that all other tools only parse the comment blocks.

I installed JSDoc 3.3.0-alpha4 from npm (on node) according to this instruction and I am trying to generate documentation for my project. As far as I can see JSDoc doesn't generate any documentation for functions or properties that don't have proper comments with relevant JSDoc flags.

I know JSDoc has gone through many iterations, has this functionality been removed or I am not using proper switches? I tried to check the command line options but couldn't find any switches for that. I am simply using it like this:

./node_modules/.bin/jsdoc -r -l my_project --destination doc/

I know there are other tools that can automatically add documentation blocks to the code, e.g. smartcomments, but it's not exactly what I am looking for. Can anyone shed some light on that?

Greg
  • 7,624
  • 4
  • 33
  • 50
  • What documentation would you expect to be generated using only a JS function header? No parameter types, no return type, no classes... – Sergiu Paraschiv Feb 20 '14 at 15:17
  • 1
    Such a tool should use the comment blocks if they are available, but be able to just use the names of functions, parameters and properties if they are not. Exactly like the comparison I mentioned says JSDoc does. – Greg Feb 20 '14 at 15:21
  • The problem is that JS is so difficult to analyse. There are no types and lazy casting for starter. This is part of why beasts like asm.js need [odd little hints](http://asmjs.org/spec/latest/#parameter-type-annotations) to tell it about variable types. Similarly, JSDoc needs you to give it comment blocks. Otherwise there's just not enough information to infer anything from. – qubyte Feb 20 '14 at 15:21
  • 1
    Note that the document you liked to says that JSDoc analyses the source that it's applied to, but that doesn't mean you don't need to comment too. It just means that you get more for your comments! – qubyte Feb 20 '14 at 15:25
  • True, it could be that JSDoc requires comments anyway (e.g. the first example on that page suggests that: http://usejsdoc.org/about-getting-started.html). However my original question still holds. Does it mean no tools will add documentation to a function if it doesn't have a comment? – Greg Feb 20 '14 at 15:31
  • One could extract a list of all the functions in a file and the names of it's parameters, but nothing else much. – Sergiu Paraschiv Feb 20 '14 at 15:52

1 Answers1

0

I have used Yuidoc for my project. It doesn't read code, only Yuidoc tags like @class, @module, @method etc... wrapped in comment block like this: /** */ You can use it as NodeJs extension and generate api by just entering in you javascript folder with Node cmd and running the command:

yuidoc .

It is a bit tricky at the beginning if you don't know how to use it.

For example if you have a yuidoc tag like so:

/**
 * @class Claculator
 * @method claculate
 * @param {Number} a
 * @param {Number} b
 * @return {Number}
 */
function calculate(a, b) {

}

/**
 * @class Graphics
 * @method drawGUI
 * @param {Number} x
 * @param {Number} y
 * @param {Number} z
 * @return {Number}
 */
function drawGUI(x, y, z) {

}

All methods/properties following the @class tag will become part of Calculator class after generation. So if you have a method called drawGUI() after calculate(a, b) and it should belong to other class, for example Graphics, than you should note that as well in another @class tag, like in the above example.

Note: From my point of view, writing comment blocks helps you improve code quality while developing and also helps you finding problems even before they happen.

Community
  • 1
  • 1
Vlad
  • 2,591
  • 4
  • 43
  • 88
  • 1
    Thanks Vlad, but as I stated in my question I was primarily interested in tools that read code, not just specifically tagged comment blocks. There is plenty of tools that can read comments tagged with keywords the tool can recognize, but not that many that are able to read just the code. Which is strange, because in other languages most tools can create an interesting output even if there are no specific comment tags added to the code. – Greg Mar 03 '15 at 16:25