expand comments section

I did some work on expanding the comments guidelines.

Any feedback is appreciated.
"the main way of documenting your public APIs" would be a bit more precise.