Documentation generator for JS client?

[delenius]

The generated client code has nice documentation comments, but I haven't been able to produce any good output from it. Is there actually a JS api doc generator that produces any good output from these sources? I've tried ESDoc, JSDoc, and YUIDoc, and all came out with essentially empty output. Is there a magic tool/configuration combo that works?

[wing328]

I don't have a direct answer to your question but the style guide we used for JS can be found here: https://github.com/swagger-api/swagger-codegen/blob/master/CONTRIBUTING.md#style-guide

Are you using any IDE with the JS API client generated by swagger codegen? If yes, does the IDE properly show the method/class documentation?

For the tools you mentioned (ESDoc, JSDoc, etc), I've not tried any of those myself so I can't comment but feel free to suggest any other style in documenting the JS code.

[jimschubert]

@delenius Are you looking for developer documentation? There's a great package called dox from TJ, the original author of express.js (and lots of other popular node.js frameworks). If you search github for just 'dox' then filter by JavaScript repositories, you'll find quite a few generators based off of dox. It's also fairly simple to use dox to manually pull all comments and output those comments to some other format. Before the express.js swagger plugin existed, I used to use dox to pull custom comments and generate my swagger spec.

Here's an example of the output from https://github.com/punkave/dox-foundation:

You can install dox-foundation, then run:

dox-foundation --source input_folder --target output_folder

[wing328]

@jimschubert @delenius I've submitted #2320 to add auto-generated documentation (markdown) for Perl. We can do the same for Javascript.

Would that meet your requirement?

[jimschubert]

@wing328 I think users generating JavaScript would probably prefer the use of modules so they can customize the documentation.

For instance, one could add dox-foundation as a dev dependency and add an npm script called 'docs':

 "scripts": {
    "test": "./node_modules/mocha/bin/mocha --recursive",
    "docs": "dox-foundation --source src --target doc"
  },
  "dependencies": {
    "superagent": "1.7.1"
  },
  "devDependencies": {
    "mocha": "~2.3.4",
    "sinon": "1.17.3",
    "expect.js": "~0.3.1",
    "dox-foundation": "0.5.6"
  }

Then, npm run-script docs will generate documentation (from my above screenshot) into ./doc. The dox-foundation generator is just one of many out there, but it does support customization of the doc template.

Is there a benefit to adding auto-generated documentation over using a module?

[wing328]

@jimschubert thanks for the feedback.

Before I decide to use a library/module/SDK, I usually take a look at the documentation first. If a library/module/SDK is poorly documented, it's unlikely I would give it a try if there are alternatives available.

In other words, the documentation is the first impression to some (if not all) developers before consuming the library/module/SDK so the auto-generated documentation (markdown) may help in that regard.

As you've pointed out, JS developers may prefer dox-foundation (or other alternatives).

To me, I think we should offer both and let the JS developers decide which one they want to use during development. (of course resource may be a constraint here and hopefully our vibrant community can fill the gap on that)

[xhh]

Regarding doc comment style in JavaScript, it seems JSDoc is the most popular one, which is also supported by dox. So I guess we should use JSDoc in JavaScript client codegen.

Regarding generating the actual doc files (e.g. in Markdown or HTML), I think providing a default template would be helpful, while other templates can be added freely as long as they recognise JSDoc tags. For example, there are several templates listed on JSDoc's github repo. dox-foundation looks good to me but it seems not be updated for 2 years (I've no idea, maybe it does not need many updates).

[wing328]

Auto-generated markdown documentation added to JS code generator. We'll keep this task open for the time being while support for other JS documentation style is being worked on by the community.