Documentation Guidelines

##Guidelines for this Wiki##

The rule of thumb for contributing documentation is "Ask for forgiveness, not permission" when you're deciding whether to document something. If for some reason your documentation is inappropriate for the wiki, you'll be notified and it will be modified. Most of the time though, your contributions are more than welcome.

##Guidelines for writing Ruby code##

Below are the guidelines for writing code for Adhearsion:

• Always use two spaces for indentation – never tabs
• Parenthesis around method arguments are optional: my_method arg1, arg1
• Parenthesis around the constructor is suggested: MyObject.new(arg1, arg2)
• Do not put parenthesis after a method signature if there are no parameters: def start
• Always put parenthesis around arguments in a method signature if arguments exist: def foo(arg1, arg2)

##Guidelines for source code documentation##

Adhearsion uses YARD for generating documentation from the source code files. Below is an example documentation for a method:

##
# Calculate a factorial on a given number.
#
# @param [Fixnum] number The number from which to calculate the factorial
# @return [Fixnum] The computed factorial of the argument given
#
def factorial(number)
    # Implementation irrelevant...
end

From this example we can see the following rules:

• The start of a documentation section should begin with ## followed by a newline
• All lines of the documentation should be separated from the line's # by one space
• The documentation instructions (e.g. @param) should be at the end of the documentation section
• There should be one empty documentation line above the method signature for readability
• There should be no empty lines between the end of the documentation and the signature line
• Try to include a @return statement
• Use professional, proper English.

For YARD usage help, see YARD's website.