Documentation Syntax

When documenting code online, it's difficult to decide on a standard for talking about the code. For now, let these simple rules apply:

  • Function and hook names should be bold. Example: hook_perm()
  • File names should be italicized. Example: uc_store.module
  • Variable names should be bold. Example: $op
  • Refer to a variable type in italics. Example: string
  • Code examples should be enclosed by PHP tags for proper highlighting.
    On pages whose input format is set to PHP, use pre-formatted tags to show code examples:
    <pre style="border: solid 1px #bbb; padding: 5px;"></pre>
  • Menu titles should be bold with greater than signs showing hierarchy.
    Example: Administer > Site building > Blocks

For hook documentation, there is a set of CSS classes you should use for a table display of keys and values. (This table can of course be used elsewhere, too.) Set the input format of the page to Full HTML and use the class "array_keys" on the table, "header" on the header row, "key" on the key cells, "type" on the data type cells, and "value" on the value description cells. For optional values, put an * after the key name and include a row at the bottom of the table that spans the entire table and contains the following in italics: *Key is optional. The value description for optional keys should specify the default value if the key is omitted.