Guide: Documentation tips

Note: If you're trying to figure out when to write documentation comments, see the 'when to comment' guide.

We're using JSDoc (the syntax and the package) to generate inward-facing documentation for our app from comments. We're also using it to write handcrafted docs as well, but that's a different thing. Here are some guidelines to get started writing documentation comments:

• See App.js for an example of a documented React component.

• JSDoc comments are block comments that start with /** (and end with */). They almost always refer to the code that comes immediately after the comment. This could be a React component, class, function, or even a local variable. File-level comments are also possible with @file in a comment at the top of the file.

• We're using the Markdown plugin, so Markdown things should work. Examples: a blank line in a comment creates a new paragraph; putting `backticks` around something formats it as code; asterisks create bullet points, etc.

• To link to another documented thing, use {@link Thing}. If it's a property of something else (like a method of a class), you'll have to use [thing]{@link Class#thing} or something similar. See here for more examples.

• To document a function or method:

  • First write a general description, on as many lines as necessary.
  • Then on a new line, write @method or @function.
    • (This is usually technically optional, but for some methods that are assigned with an equals sign (for this-binding reasons), you need @method for JSDoc to recognize it correctly. Therefore, for consistency, we'll always include this annotation.)
  • Under that, for each parameter x, put @param {type of x} x - description of x.
    • If a parameter has a member y that is also important, you can document it after x as @param {type of y} x.y - description of y. (And so on, for nested objects.)
    • If a function takes destructured parameters, like const myFunction = ({ innerParam }) => { ..., you have to give a name to the outer object (the object that's actually passed in) and document it as a parameter before you document the inner param(s) (as described above). To be consistent, you can use the following names for outer objects if nothing else seems more appropriate:
      • params if it's a regular function
      • props if it's a functional React component (since that's what we would normally call it if it wasn't destructured).
  • Finally, if the function returns something, after the params, document that with @returns {return type} description of return value.

• To document nested keys of an object, such as the state of a React component, you can use @property in the same way as you would use @param for a function. First describe the object generally at the top, then document each key with an @property line. They can be nested as deep as you like, but a parent object has to be described before you describe its children. So if you have a line like @property x.y - something, you should have a line like @property x - something else above that. Note that in this case, x is a key of the top-level object, not the top-level object itself.

• When documenting a class (React component or otherwise), you can put the constructor parameters (props for a React component) in the same comment as the class description. We're going to prefer it this way because it looks cleaner. Just use @param in there and it should work.

  • Also, if the class extends something (like React.Component), don't forget to use an @extends annotation to make note of that.

• (If you have more tips, feel free to expand this page!)