Add in code documentation standards. #4530
Conversation
I might have missed it, but I did not see anything detailing the in code documentation standards. Here is an addition to the CONTRIBUTING.md, with a base line standard.
|
Maybe this should be added to https://github.com/WordPress/gutenberg/blob/master/docs/coding-guidelines.md instead? |
|
Maybe both. I knew there was another file! |
|
I would also vote for |
|
|
||
| This project uses [JSDoc](http://usejsdoc.org/) for doc blocks. Inline code should be used for describing individual pieces in detail. The in code documentation will hopefully in the future be repurposed for [the WordPress code reference](https://developer.wordpress.org/reference/). If you would like to help contribute to the in code documentation, try adding a JSDoc header to something that needs one! It would be greatly appreciated! | ||
|
|
||
| In code documentation priorities: |
There was a problem hiding this comment.
How did you come to this prioritization? Should we set prioritization expectations, or merely that all things are to be documented (prioritization implies that you don't need to document everything)?
There was a problem hiding this comment.
How did you come to this prioritization?
I believe I went off of what was already documented, and what seemed undocumented (higher undocumented rate lower on prioritization). We can take that part out.
I wrote this for feedback, I have no idea if there should be prioritization. I would probably be most in favor of documenting everything so we can potentially extract the docs out programmatically, but we did not come to a consensus in the JS meeting. Without your and Riad's buy in, since ya'll are doing the vast bulk of the work, it would be unfair to try to impose anything on you two.
I might have missed it, but I did not see anything detailing the in code
documentation standards. Here is an addition to the CONTRIBUTING.md,
with a base line description. As we figure out what we want to do regarding components we can revise this.