Use cases for jsdox?

[mrjoelkemp]

From @boneskull:

@psq I'm not really understanding the use case of jsdox against anything but very small codebases. If you have one file, you can generate a README.md from it (sort of; the file won't be named README.md and it won't go where you want, but that's another open issue). If you have multiple files, you get a directory (or directory hierarchy) full of Markdown files.

Is the user to browse them individually? They don't make a web site. They can't be used with Jekyll because they have no Front Matter. You could potentially create an entire GitHub wiki out of the non-hierarchical files (using -r; not -rr), but a wiki is not really suitable for API documentation. Does some other converter consume them and turn them into a PDF?

I've only used jsdox for a very small module or two b/c of its limitations. If it generated a Jekyll site (and had more tag support, of course), then it's a viable alternative to jsdoc itself.

[mrjoelkemp]

Just to chime in a little bit.

Is the user to browse them individually?

The output folder is definitely traversable via github. With grunt-jsdox, you can also generate a table of contents to make navigation a tad easier. It then resembles a wiki while respecting the directory structure of the codebase.

They can't be used with Jekyll because they have no Front Matter.

I never thought of this use case. That sounds like like an interesting feature. I haven't used jekyll before, but if we could create a site similar to what jsdoc generates for html, then that would be pretty useful. Ideally, this shouldn't be too bad to implement (prefixing all generated markdown files with the front matter) once the codebase is cleaned up #72 for ease of introducing new features.

had more tag support

This is a necessary headache – though it should get easier. Without tests for our analyzer #51, it's tough to modify the ast generated from lib/analyze to support additional tags.

At the moment, I'd say we're like the jsdoc haruki template piped into Mustache for markdown generation.

Ideally, we'd have feature parity with the html docs generated from jsdoc (line numbers, thorough tag support, etc). That's a long ways out without more contributors.

Personally, I think jsdox has the potential to be the easiest markdown generator to use (especially since we're using jsdoc's parser and not hand-rolled parsers like many other solutions).

[psq]

Is the user to browse them individually?

The output folder is definitely traversable via github. With grunt-jsdox, you can also generate a table of >contents to make navigation a tad easier. It then resembles a wiki while respecting the directory structure of the codebase.

This was the initial idea, to generate the .md file and upload to github. I also sometimes browse the files locally with Marked.app, the forward links work, but there's no back button I could find, so limited (but still useful at least for checking the files looks good)

Other possibilities were for people to add a post process step to generate a mini site (like jekyll). Or to embed jsdox in something else, and process the files from your node app (that's what the grunt task is doing.

They can't be used with Jekyll because they have no Front Matter.

Today, you could create your own templates and add the Front Matter prolog to the generated files. This should probably work.

[boneskull]

This was the initial idea, to generate the .md file and upload to github. I also sometimes browse the files locally with Marked.app, the forward links work, but there's no back button I could find, so limited (but still useful at least for checking the files looks good)

This may be a good exercise, but has limited use to a wide range of users. I don't know why I would just want to generate some documentation that could be manually browsed on GitHub. That's not easy or fun.

My wish list:

1. Full tag support. The problem with non-jsdoc tools that want to be jsdoc is that they only support a limited range of tags, so people just use jsdoc (dox, I'm thinking of you).
2. First-class support (in other words, don't make people wire it together themselves) for a static site generator like Jekyll would be great for this project. Web sites have a broader appeal than GitHub directory structures. This behavior should probably abstracted into a plugin or adapter. I would be interested in making this the default behavior, so you could say "this is jsdoc, it makes a Jekyll site from your docstrings" instead of "it makes a directory structure of Markdown files from your docstrings." You would be able to then switch off this behavior.
3. Ability to pipe all output to one file. This can be accomplished via other things like find/concat or grunt-contrib-concat, but the easier the better. This is a command-line switch. It's a "nice-to-have".

I will try to make time to send more PRs if we agree this is the direction we want to head. Another similar project is jsdoc-to-markdown which I have also contributed to. Unfortunately neither of these fit my needs at the moment.

[mrjoelkemp]

Thanks for your thoughts, @boneskull

Regarding 2 and 3, my vote is in favor of having a configurable tool that can easily fit multiple use-cases.

Regarding 1, we could definitely use some help.

[psq]

Indeed, thank you for the feedback @boneskull.

At the moment, jsdox does what I needed (and much more now), but pull requests along what you outlined are definitely welcome by all.

[monken]

This is what I put in my package.json file:

{ "scripts": {
    "docs": "jsdox -i index . && cat output/{module1,module2,module3}.md LICENSE > README.md"
  }
}

This will concatenate the files I choose in the order given in the command and append the LICENSE file as well. You can add as many files as you want to that cat command, e.g. to add an introduction.