Documentation tool change proposal

[peppsac]

I wrote some documentation over the past few days and I feel that jsdoc isn't quite the tool I need.

As I may not be the only feeling this way I propose to discuss this issue here to settle the choice on our documentation tool.

My main issue regarding jsdoc is its special syntax: it clutters the code with information only useful to their tool (@param, @constructor, etc).

I took a quick look at other tools, and found docco which is really nice. Basically it puts no constraint on the programmer, and simply generate a documentation site from the comments in the code (see http://coffeescript.org/#literate for the inspiration).

https://github.com/iTowns/itowns2/tree/documentation is my attempt at using docco for itowns. You can test by using the new command npm run doc2 or you can see the result here: http://37.187.164.233/itowns-docs/

A few notes:

• I've modified 2 examples, so they are documented and functionnal on the API doc site
• take a look at the source code of the commented files when using Docco (e.g https://github.com/iTowns/itowns2/blob/documentation/src/Core/View.js)
• I modified docco to add a few short cut for our use case:
  • internal autolink: if you write "Camera*" it will automatically insert a link to the documentation of Camera
  • sidebar generation (as request by @vcoindet :)) and fuzzysearch (using implementation from https://blog.forrestthewoods.com/reverse-engineering-sublime-text-s-fuzzy-match-4cffeed33fdb#.7i6md382t)
  • public function signature extraction
• docco is a 200 lines project, so it's very easy to adapt :)

Let me know what you think :)

[vcoindet]

Nice work ! I have to say, I wasn't conviced at first by the result, but I think we can do something better with docco than with jsdoc. It seems to be cleaner with docco ! ;)

I have a few observations on the result :

• jsdoc natively propose tables to describe parameters of the functions and I think it's more clean and more readable. It is probably possible to do tables with docco (as it is in mardown) but the effort will more important and the maintenance too...
• thanks for the sidebar : do you think its position can be fixed, so when we scrolled it would always appeared on the screen ?
• fuzzysearch is a really good thing, do you think we can use it for all methods (such as addLayer for example) ?
• the "show/hide code" is better than in jsdoc ! ;)

[peppsac]

Thanks for your feeback @vcoindet :)

• tables for arguments: yes you can use the markdown syntax for tables.

name	type	Description
crs	String	View's referenceCrs
viewerDiv	Canvas	DOM container of View's <canvas>
options	{}	foo

but the syntax is a bit ugly and it's painful to do multiline entries...

• we can tweak the layout like we want: it's plain css :)
• we could search in methods as well but currently the sidebar only contains class names

Since you write quite a lot of itown's doc, how do you feel about changing the syntax from jsdoc to markdown?

[tbroyer]

I'm not a big fan of literate programming, but more importantly I don't think it can be retrofitted into an existing codebase. Literate programming can be a really good fit for examples though; but when it comes to APIs, you want structured comments.

BTW, I don't quite follow your opinion that JSDoc requires special syntax, while you're forcing yourself to do the same except using formatting rather than "tags". This means, for example, that if you one day decide to use tables for arguments rather than lists, you have to rewrite all your comments. With structured comments, the structure is already there, and only the tool that processes them needs to change.

Finally, there are many tools that work with JSDoc and bring them to their full potential:

• display documentation right in your editor (e.g. when hovering a class/method, or in autocompletion popup menus, or for method arguments as you're typing them; i.e. what's called IntelliSense by Microsoft, and other similar tools)
• automatically generate skeleton JSDoc comments from the code in your editor, when you only have to fill in the blanks
• can generate .d.ts files for TypeScript (or Kotlin, or GWT), or library definitions for Flow
• can be used to do typechecking with tools like Closure Compiler (or TypeScript, or Flow), and can help those tools with optimizing/minimizing code

So, no, I wouldn't use anything else than JSDoc annotations to document the API (Docco could be good to document examples though, as said above).

[peppsac]

Thanks for your feedback @tbroyer .

I'm not a big fan of literate programming, but more importantly I don't think it can be retrofitted into an existing codebase.

I don't propose to use litterate programming, except for examples. And I believe we can change our commenting system, given the fairly low count of comments in our codebase.

Literate programming can be a really good fit for examples though; but when it comes to APIs, you want structured comments.

I believe you meant to write "I want" :) Structured comments is nice and all, but I'd prefer to have something easy to read/write for a human instead of focusing on the machine/tool that will parse them.

BTW, I don't quite follow your opinion that JSDoc requires special syntax, while you're forcing yourself to do the same except using formatting rather than "tags" [...]

Again, I prefer reading and writing markdown + some tailored shortcuts (such as Camera*) to jsdoc, that's it (this debate already happened a decade ago and json won over xml :))

Finally, there are many tools that work with JSDoc and bring them to their full potential:

• display documentation right in your editor [...]

Indeed could be handy.

automatically generate skeleton JSDoc comments from the code in your editor, when you only have to fill in the blanks

This is a recipe for disaster IMHO. From my experience, these kind of "fill in the blanks" comments are useless because again, they are written to please a tool, not the reader of the comments.

can generate .d.ts ...

Do we care about this?

can be used to do typechecking ...

Yeah maybe, but that's focusing on maybe long term goals, while forgetting about the most important ones: writing useful documentation without cluttering the source code.

[tbroyer]

Forgot to mention in my previous comment: it looks like you had to change inline comments from // … to /* … */ so they're properly ignored by Docco. Add to that that it only applies to a few files, and you'll find in a few weeks/months from now that the rule wasn't strictly followed and your doc need some cleanup. Structured comments on the other hand, appear at specific locations and have a specific format (/**); it's hard to mess the doc by mistake (possible, and relatively easy, to inadvertently hide some doc by using /* instead of /**; but highly unlikely to end up with non-doc comments inside the doc).

Structured comments is nice and all, but I'd prefer to have something easy to read/write for a human instead of focusing on the machine/tool that will parse them.

Weren't you talking about using markdown tables for arguments? ;-)

But more importantly, the people reading the documentation won't read it where you write it, by a very wide margin. They'll mostly read the generated HTML doc that's published online, or the tooltips/popups showing up in their editor of choice. This is what should be optimized for.

Again, I prefer reading and writing markdown + some tailored shortcuts (such as Camera*) to jsdoc

Fwiw, JSDoc can use markdown too: usejsdoc.org/plugins-markdown.html, but yes, you'd have to type {@link Camera} rather than Camera* (unless you create a jsdoc plugin; but I wonder how this syntax plays out with markdown's own *foo bar* baz, might not be worth it)

can generate .d.ts ... Do we care about this?

What will you say to people who'll want to use iTowns in their TypeScript/Kotlin/Flow/etc. projects?

can be used to do typechecking ... Yeah maybe, but that's focusing on maybe long term goals,

This is not about typechecking within iTowns, but in projects that will possibly use iTowns. It's not about you/us, but about your/our users.

while forgetting about the most important ones: writing useful documentation without cluttering the source code.

Well, then we disagree. While I agree documentation shouldn't be a pain to write and maintain, it must not be at the detriment of iTowns users. JSDoc is much more than an HTML generator, its syntax is used by many tools, and even goes beyond documentation. Again it's not about you/us, but about your/our users. “Focus on the user and all else will follow.”

[peppsac]

Regarding your /** versus // comment : that's why we have reviewers, so we get another pair of eyes looking at the changes.

The rest of your post reads like : "if you're not using jsdoc then you're anti-users" and obviously I disagree :)

As an example of why I disagree see three.js: they don't use jsdoc and they seem to do very well :-)

[tbroyer]

Regarding your /** versus // comment : that's why we have reviewers, so we get another pair of eyes looking at the changes.

Easily missed even for trained eyes (and you have to either apply the rule everywhere or also check which file is being changed; cognitive overhead)

Or you could have automated checks that // comments only appear, in those files, at places where you'd expect API documentation. …or you could use a tool that only looks at what you want it to look at and ignore the rest ;-)

The rest of your post reads like : "if you're not using jsdoc then you're anti-users" and obviously I disagree :)

That's not what I'm saying.

What I'm saying is that there are many tools (jsdoc, esdoc, closure-compiler, editors) all sharing one syntax (jsdoc), bringing lots of benefits for the users; and you propose using a "quick and dirty" (that's from the readme), patched !, tool (that also imposes cognitive overhead to code-reviewers) just because you don't like that syntax.

You don't have to like it (jsdoc), but weigh up the pros and cons before choosing something else. The pros and cons of using a syntax everyone knows (for those reading the source and maintaining the doc) that comes with many tooling (for the users), vs. a tool that's small and fun to use (and patched, so a fork, that will have to be maintained!) but imposes restrictions (// for doc comments, /* for code comments) and conventions (the way you decide the describe arguments, so the doc style is consistent) that will have to be thoroughly documented, and reviewed (and there will be mistakes, and because it's about documentation, users will notice them long before you do).

Fwiw, with the jsdoc syntax, you can also have name-checking of the arguments vs. the doc: if you rename or remove an argument, a tool can tell you the doc no longer matches the function signature; and if you add an argument, it could tell you you forgot to document it; I suppose it could also tell you if the doc and signature order doesn't match (because it's much easier to read docs if it documents arguments in order).

I see many more pros for jsdoc than for docco, and only few cons, compared to many cons for docco. This is in part subjective, so do the exercise yourself and share your results.

As an example of why I disagree see three.js: they don't use jsdoc and they seem to do very well :-)

I wouldn't use three.js as an example.

Afaict, they were very late to adopt NPM (publish official packages there) to begin with; but fortunately there were people who packaged and published the library. And fortunately, there are people who maintain .d.ts files so you can have good autocompletion in editors (and typechecking, in editors and/or with TypeScript), but almost no documentation. You have to jump to threejs.org for that (you cannot even jump to the code, because documentation isn't there, at all, in any form)

[peppsac]

I'll try to answer all your points. If I missed some please tell me :)

• // syntax and "cognitive" overhead: as stated earlier we could simply adopt the /// from Rust for documentation. Actually Rust documentation is a really good inspiration IMHO - I even considered using rustdoc for itowns :) See https://facility9.com/2016/05/writing-documentation-in-rust/ or https://doc.rust-lang.org/book/documentation.html for more info
• using a patched tool instead of an established one: I agree it can be a problem. But in this particular case, the tool is 200 lines long and it works as expected so.. what problem do you foresee? On the other hand, note that jsdoc is pretty inactive (no real activity since 2015 according to git logs).
• loosing support for all the tools built around jsdoc syntax: yes I agree, it's a loss. But again, three.js does very well without.
• jsdoc syntax vs markdown syntax : IMHO it's a big issue. To me, jsdoc syntax is built for the tools that will process it, while markdown is buillt for the reader/writer of the markdown. jsdoc is full of tags (@param, @constructor, etc) which I consider being noise: their only purpose in the source code is for the tool parsing the file. markdown on the other hand is easy to read / write: I think you can agree with me on this one given the number of tools/website that now use markdown syntax.

So, assuming the end result (generated html site) is more or less equivalent with both tools, I believe the discussion can be summarized as :

• do we want to use tools taking advantage of the jsdoc syntax => let's stick with jsdoc
• do we want to ease doc reading/writing => drop jsdoc and pick a tool that works with md syntax (might be docco or something else)

By the way I'd love to hear from other dev since we aim for a first release soon, so choosing the documentation tool is quite urgent :)

[tbroyer]

as stated earlier we could simply adopt the /// from Rust for documentation.

I don't see where you proposed that.

Actually Rust documentation is a really good inspiration IMHO

Yes, except Rust is statically typed, so you don't need to document arguments if the type and name alone are self-sufficient (Go doesn't have structured comments either fwiw). JS is different, and jsdoc has the benefit of adding machine-readable type hints.

note that jsdoc is pretty inactive (no real activity since 2015 according to git logs).

There's esdoc and documentation.js too (among others); all relying on the same syntax.

jsdoc syntax vs markdown syntax : IMHO it's a big issue.

It's not really jsdoc vs markdown (jsdoc can use markdown too), it's more freestyle description vs. structured markup. The latter can be read by tools (for IDE inline help/completion, type checking, interop with other languages that compile down to JS), separates content from presentation (e.g. whether to present arguments as a list or a table), and can be checked/validated/linted (http://eslint.org/docs/rules/valid-jsdoc)

jsdoc is full of tags (@Param, @constructor, etc) which I consider being noise

fwiw, I'd argue for omitting any tag that can be inferred statically from the code (e.g. @class and @constructor are redundant when using ES2015 classes), so most of the time you'd only use @param and @returns (if only to add type hints)

markdown on the other hand is easy to read / write: I think you can agree with me on this one

If we replace "markdown" in this sentence with "freestyle documentation of arguments", then I'm afraid I have to disagree.

But I think my point is more about: when there's a "standard tool/syntax" and you're bikeshedding about using something else (and in this case a "custom" tool), you're just wasting time and energy. When there's a standard syntax, use it; you don't have to like it.

By the way I'd love to hear from other dev

:+1:

[gchoqueux]

+1 for JSDOC

[nosy-b]

I've close to 0 experience in Documentation tools in JS so my point of view is worth close to 0 too :) but I share the idea that it's better to follow a standard tool. JSDoc is stable and maintained and i'm personally not allergic to its syntax. @gcebelieu, any advices?

[vcoindet]

+1 for JSDOC

[autra]

I don't know yet :-)

[autra]

(but if we stick with jsdoc, we will need the markdown plugin, that's for sure)

[Mkonini]

I'm for using a standard and structured tool, JSDOC

[gcebelieu]

@gcebelieu, any advices?

To document geoportal apis : https://github.com/IGNF/geoportal-access-lib/ , https://github.com/IGNF/geoportal-extensions/ and https://github.com/IGNF/geoportal-sdk/ we're using jsdoc with its jaguar-js template (https://github.com/davidshimjs/jaguarjs-jsdoc). We can include jsdoc tags and also use markdown syntax.

I havn't practiced the other tools mentionned. My approach, for long term project is to give privilege to widely used and tested solutions vs brand new ones if both fit the needs.

[peppsac]

Replying 1 month later...

as stated earlier we could simply adopt the /// from Rust for documentation.

I don't see where you proposed that.

Yes I forgotten that I had removed that part in an older comment. But you forgot to answer to my actual question. Is the cognitive overhead still that bad if we use the /// syntax ?

Actually Rust documentation is a really good inspiration IMHO Yes, except Rust is statically typed, so you don't need to document arguments if the type and name alone are self-sufficient (Go doesn't have structured comments either fwiw). JS is different, and jsdoc has the benefit of adding machine-readable type hints.

So what? You're missing my point, again. The Rust documentation is well written and aimed as the user - it's completely unrelated of the type system.

note that jsdoc is pretty inactive (no real activity since 2015 according to git logs).

There's esdoc and documentation.js too (among others); all relying on the same syntax.

documentation.js is a 1 year old project, with 1 main contributor... And, again, you didn't answered my question: what problem do you foresee with using a patched 200 line tool?

Also in a previous comment you didn't explain why "[you] wouldn't use three.js as an example". Given the popularity this project has, I wonder what make you so confident about asserting this?

jsdoc syntax vs markdown syntax : IMHO it's a big issue.

It's not really jsdoc vs markdown (jsdoc can use markdown too), it's more freestyle description vs. structured markup. The latter can be read by tools [bla]

Sure. But that's exactly what I wrote: jsdoc is tool oriented, markdown is reader/writer oriented. And given that the resulting html is equivalent, I prefer losing tools and get better code comments.

markdown on the other hand is easy to read / write: I think you can agree with me on this one

If we replace "markdown" in this sentence with "freestyle documentation of arguments", then I'm afraid I have to disagree.

Sure. But if I replace your sentence with "the Earth is flat", I'll have to disagree too.

But I think my point is more about: when there's a "standard tool/syntax" and you're bikeshedding about using something else (and in this case a "custom" tool), you're just wasting time and energy.

Hmmm... sorry but I'm not bikeshedding. The documentation of iTowns is bad. Period. I'm trying to get things in a better shape, and I strongly believe that the tool used has a big influence. Now you can disagree, but dismissing efforts from other people as bikeshedding isn't appreciated.

When there's a standard syntax, use it; you don't have to like it.

Is that supposed to be an argument?

[tbroyer]

Actually Rust documentation is a really good inspiration IMHO

Yes, except Rust is statically typed, so you don't need to document arguments if the type and name alone are self-sufficient (Go doesn't have structured comments either fwiw). JS is different, and jsdoc has the benefit of adding machine-readable type hints.

So what? You're missing my point, again. The Rust documentation is well written and aimed as the user - it's completely unrelated of the type system.

Yes it is (IMO).

(the keywords are “machine-readable type hints”)

note that jsdoc is pretty inactive (no real activity since 2015 according to git logs).

There's esdoc and documentation.js too (among others); all relying on the same syntax.

documentation.js is a 1 year old project, with 1 main contributor...

But it doesn't really matter, because the changing the tool doesn't change the documentation syntax. You can choose to use jsdoc today, change to documentation.js tomorrow and switch to esdoc the day after, it'll only affect the generated HTML doc, without any impact on your code comments; the inline doc in your editor is independent, the type-checking with your compiler/linter (and editor) is independent, etc. Because all those tools use the same standard syntax as input.

Also in a previous comment you didn't explain why "[you] wouldn't use three.js as an example".

One example: https://threejs.org/docs/index.html#api/loaders/TextureLoader.setWithCredentials This API has been removed 6 months ago and shipped in 3 versions already. And for reference it was added less than 6 months earlier and shipped in 4 versions before being removed. This is one example I spotted these last days, there may be other similar discrepancies, maybe not; and if you had used the property rather than the setter you could have seen the behavior changing without noticing (this is an argument for type-checking), and checking the docs wouldn't have helped you.

Also, it's been one year and 9 versions that setCrossOrigin will return the TextureLoader, allowing fluent/chaining calls; and it's not documented, so one would really wonder why there are both a property and a setter and which one should be used.

Three.js API documentation is managed like the non-API documentation, totally decoupled from the code it documents. I admit this is not what you're proposing, but it answers the question: I definitely wouldn't use three.js as an example of how to do API documentation (in terms of tooling, syntax and workflow).

I prefer losing tools and get better code comments.

And this is I believe the crux of our disagreement (also, standard syntax vs. custom syntax).

[gchoqueux]

JsDoc was chosen.