JSDoc-Comments

[Rukenshia]

Point 17.1 shows JSDoc comments, but it is not actively mentioned somewhere. I think that you should mention to document functions using JSDoc.

[jeromeetienne]

+1

[hhsnopek]

Do you actually use JSDoc or just comments similarly to JSDoc spec? (question for airbnb devs)

[ljharb]

As far as I know, we do not use JSDoc. -1 from me.

[justjake]

I use JSDoc-like comments but don't actually generate documentation from it, or validate my JSDoc type annotations in any way. I would like to add JSDoc to our styleguide, but it's a large topic, and one with its own style considerations

[jeromeetienne]

Personnaly i use it with jsdoced.js. It generate type checking during my test. if the jsdoc isnt respected at runtime, it will throw an error to notify me. http://jsdocedjs.org

+1 to push for jsdoc :)

[BMorearty]

How many times are you going to vote, @jeromeetienne? 😜

-1 from me for adding JSDoc (or any structured doc format).

[jeromeetienne]

@BMorearty oops sorry, bad memory :)

[ljharb]

I'm going to close this for now, as we pretty consistently do not use JSDoc internally at Airbnb.

If an internal consensus forms around using it, then we can revisit it here.

[jufemaiz]

@ljharb just out of interest, what direction has Airbnb gone with for documentation of javascript?

[ljharb]

Manually documenting APIs; if an API is too complex to easily document manually, the API is too complex, and that needs to be fixed.

[jufemaiz]

Whoa - that was unbelievably fast! Thanks for your comments!

Just for clarification, Airbnb doesn't go down the path of inline documentation?

[ljharb]

Somewhat - comments should never answer "what" - only "why", providing history/motivation. Anything beyond that serves to lure you into a false sense of confidence that your code is clear enough by itself - clear code doesn't require documentation to explain what it's doing.