Add documentation on writing codebase docs.

Review Request #7896 — Created Jan. 18, 2016 and submitted


Review Board


This covers how to document source code in our projects. It goes over
the Python and JavaScript documentation syntax we are or will be using,
the format we use for listing arguments and return values and such, and
other guidelines we have for the documentation.

The JavaScript doc guidelines don't actually match what we have today.
Instead, it's more of a proposal for what we should do going forward.
The reason is that, in researching options for generating codebase docs,
I've found that what we're doing isn't going to be sufficient. So this
covers a new set of standards that we can fairly easily start moving to
as we go.

Built the docs and read through them. Checked all links and references,
and checked for spelling errors.

Description From Last Updated

Too many blank lines here.


These should be capitalized, no?

  1. Tool: Pyflakes
    Ignored Files:
    Tool: PEP8 Style Checker
    Ignored Files:
  2. Show all issues

    Too many blank lines here.

  2. docs/codebase/docs/writing-codebase-docs.rst (Diff revision 1)
    Show all issues

    These should be capitalized, no?

    1. So I was thinking so initially, and was using/recommending that. Then I dug in while I was writing these docs, looking at what others do and what's appropriate.

      According to Mozilla's docs, these are the actual fundamental types, under the hood. You can't use them directly, but they're what's probably most appropriate. Other doc systems recommend using these when dealing with such primitives. Things like String and Object are implementations of those primitives. So, I went with these, to help distinguish them. I'm not married to this, though.

    2. That sounds to me like "under the hood" means "in the SpiderMonkey implementation". The ECMAScript specification uses capital letters for these types.

    3. Maybe, honestly wasn't sure. Just went and dug into a bunch of the more popular JS libraries and doc solutions. Here's what I found.

      YUIDoc shows examples using String, Boolean, etc. jQuery uses this format for their docs (sorta -- they make up a lot of types like "htmlString" and "Selector" and "Integer" such, so I think it's more about creating consistency there and not about truly referencing JS types).

      JSDoc, ESDoc, Sphinx, and documentation.js show examples using string, boolean, etc. pdf.js, Angular, React, and Lodash use this format. This seems to be the most common form out there amongst libs that document types.

      Plenty of libraries don't even list types in their docs, but that's not ideal.

    4. Well, my vote is for using what the ECMAScript spec uses :P

    5. Yeah I don't know, maybe. I'm not sure that what ECMAScript is doing is really the same thing. The same docs that reference String and Object also reference Null, Undefined, List, and some other things that aren't actually types in JavaScript. I think that's more spec-level definitions and not documentation definitions. ECMAScript even documents that string, boolean, etc. are the primitive types behind String, Boolean, etc. (which they are, so of course that makes sense).

      Google also recommends string, boolean, etc. JSDoc, apparently, won't even allow Boolean and String, and is considered the gold standard in doc formats for JavaScript. The more I look, the more I see the trend swinging to these types. So I think that's really the right way to go.

    6. Very well.

Review request changed
Change Summary:
Pushed to release-2.5.x (ee855e7)