Documentation Examples

documentation_examples.md

We should document fields, properties, methods, classes, and anything that would benefit from additional information besides the code itself. The sweet spot is to write enough to provide a meaningful idea of the purpose, without going overboard and writing in too much detail or things that are too obvious.

For example, if the name of a parameter already hints the type and purpose, we shouldn't need to provide additional information about it.

Which format to use?

While there are many documentation formats, which vary depending on the language we are using, I personally like the minimal syntax of TOMDOC, which anyone can easily pick up and read just by having read a few examples.

We use that same doc syntax both in Ruby and JS, and it's really nice.

What about generated docs?

For Ruby, you could use yard-tomdoc, which will compile that simple syntax into nice readable docs.

Generating documentation pages like that is typically more useful for gems and libraries than for apps.

Examples

Next are a few examples to illustrate how it might look like in Ruby and JS.

Fields or Properties

# Public: Abbreviation of a few words that sums up what the question is about.
# Example: 'Side Effects'
field :title, type: String

// Public: We debounce the search request to prevent the user to trigger
// several searches while typing.
searchDelayInMillis: 500,

// Public: Whether the layer should be visible (still transparent but dark).
mask: { type: Boolean, default: false },

Methods

# Public: Update the user's password if all the validations are fulfilled.
#
# Returns true if the password was successfully changed.
def update_with_password(params, *options)
  ...
end

// Public: Allows to add/update/remove a query parameter in the current URL,
// using the History API.
//
// queryParams - An object where its properties represent query string parameters.
export function replaceQuery (queryParams) {
  ...
}

# Public: Formats a number like currency. Example: $1,234,567,890.50
def currency(amount)
  ...
end

// Internal: Builds the mapping, from alias to icon file path.
//
// NOTE: Checks that we don't define the same icon twice.
function addIcon (name, folder, file) {
  ...
}

Classes

# Public: Allows to keep track of web requests and store related metadata.
class Ahoy::Event

# Public: Contains information about a page visit. Associated to an Ahoy event.
class Ahoy::Visit