Javascript: 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? :stuck_out_tongue_winking_eye:

-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.