Guidelines for Layout oriented Documentation

WIP

General

• Multi-line comments are reserved for documentation targeted at layout creators.
• Markdown is the only format for documentation targeted at layout creators.
• Use (multiple) single-line comments for normal code documentation.
• Indent comment blocks with tabs. Indent with spaces inside the comment block.
• Code examples inside comment blocks should be indented with 4 spaces.
• Comment blocks should not expand beyond the 120th column.

Types

• Provide types as inline code where they need to be highlighted: StatusBar
• WoW types in PascalCase, Lua types in lowercase.

Documentation Header

• The documentation header is at the top of the file.
• Start the header with a title in the following format: # Element: Name of the Element.
• Provide a short description of what the element does, separated from the title with an empty line.

Header Sections

• The documentation header consists of several sections.
• Each section is introduced by a section title: ## Section Title.
• The section contents are separated from the title by an empty line.
• Sections are separated form each other by an empty line.

Section Order

• Widget
• Sub-Widgets
• Notes
• Options
• Sub-Widget Options
• Attributes
• Examples

General section contents

• The Examples and the Notes sections adhere to different rules. See below.
• Each section consists of one or more name-description pairs.
• The name and the description of each pair are separated by - and are on the same line.
• Descriptions are to be aligned so that each - is on the same column.
• Left-align the names.

The Widget Section

• name - the table key that oUF expects to find on the unit frame in order to register the element.
• description - should specify the expected widget (or Lua) type of the table key value and what it is supposed to represent or hold. Given that all WoW widget types are Lua tables, either the widgets that form the array part of this table or the table itself are considered the main widgets. I.e. for the Runes element, oUF expects an array named Runes holding StatusBars, where those are then considered the main widgets. For the Power element, oUF expects a StatusBar widget named Power, where it itself becomes the main widget.

Sub-Widget Section

• name - a sub-key of (one of) the main widget(s). Should start with a ..
• description - should specify the expected widget type of the sub-key value and what it is supposed to represent or hold.

Notes Section

• Contains a short description of special cases or default values set by the element.

Options Section

• Contains a list of options available to the layout for fine-tunning and better control.
• Options are always key-value pairs in the main widget(s).
  • name - the option name prefixed by a ..
  • description - description of what the option does and possibly its default value.

Sub-Widget Options Section

• Same as the Options Section, but for sub-widgets.
• Sub-widget options are always key-value pairs in the sub-widget(s).

Attributes Section

• Key-value pairs set by the element as means of communication with the layout.
• Some attributes are only meant for internal communication and should not be documented using Lua's multi-line comments --[[ ]].

Examples Section

• Contains one or more simple element usage example(s) as Lua code.

Functions

• DO NOT document internal functions using Lua's multi-line comments --[[ ]].
• The following does not apply to documenting internal functions.
• Document functions at their first occurrence in the code (counted from the top of the containing file).
• Start with the type of the function followed by a colon and a space. Currently Callback: or Override: .
• Use colon notation like element:FunctionName(arg1, arg2, ...) or dot notation to stress on different self element.FunctionName(self, arg1, arg2)
• Use the function name that will be used by the layout: element.Override() instead of element.Update()
• Provide a short description of what the function does on a new line after the function name.
• Separate the function description and the argument list with an empty line.

Function Arguments

• Use a separate unsorted list item for every argument. Use * instead of - to introduce the list item.
• The first argument should always be self.
• Provide a short description after the argument name on the same line.
• Separate the argument name and description by -.
• Align descriptions so that all - are on the same column.
• Left-align argument names.
• Append the argument type in round brackets to the end of the argument description: (number)
• Append a question mark to the type if the argument value might be nil: (number?)
• Provide value range in square (for inclusive) or round (for non-inclusive) brackets after the type if applicable: (number)(0-1]

Function Return Values

• introduce a separate unsorted list for return values by using ## Returns followed by an empty line
• the rules for function arguments apply here