Gutenberg: Should we add JS Doc comment blocks?

[BE-Webdesign]

_Tried finding a related ticket to no avail, so apologies if this is a duplicate._

Issue Overview

Should we add JS Doc comment blocks for functions, components, etc.

Pros:
Provides quick references for what each piece is expected to do.
I believe WP Core uses JS Doc as part of its core standards? (vaguely recall)

Cons:
Adds to the maintainability burden, especially as things are changing quickly, docs go stale and are rarely updated to match new functionality/meanings.

[ntwb]

During WP 5.0 there will be a new initiative kicking off (it's been ongoing for a few months now in stealth mode) to document the entire JavaScript codebase:
• https://make.wordpress.org/core/handbook/docs/inline/js/

So, with that said, it would be great to have Gutenberg also use JSDoc, how and when that should occur here in Gutenberg is probably best decided by the @WordPress/gutenberg team

[youknowriad]

Yeah, We already agreed on using JSDoc and I believe we're already using it sparsely. We should improve our linting to help us in the process of adding those.

I also suggest starting with the "exported" functions, components ... first. Internal functions (event handlers ....) can be added later because less important.

[gziolo]

I also suggest starting with the "exported" functions, components ... first. Internal functions (event handlers ....) can be added later because less important.

Totally on board with this idea 💯

[youknowriad]

I guess we all agree on adding more JS Doc, I'm closing this issue. And please add JS Docs :)