GoodDoc for Ruby

gooddoc-v0.1.txt

GoodDoc for Ruby

Purpose
Provide a code documentation specification for Ruby that doesn't faff about.

Method documentation
The first sentence should be a one-sentence summary that starts with the name being declared.
This is the only part of the documentation that is required. If the public or private status 
of the function would be in question, you should work it into this summary. Use the active 
voice when possible, for instance returns or checks is better than will return or will check.

Any further sentences can go into the caveats of the function, or a longer description. Do not
add an empty comment line between the longer description and the one-sentence summary.

If you need to document the params, you should add a empty comment line, then add the params
by writing the param name, then a " - ", then the description of the param. If you 
document one param, you should document all params.

If you need to document the return value because it is not obvious, then you may add an empty 
comment line, then the word Returns, then the type and description of the return value. 
Obviously functions ending with a question mark return a boolean like value and to_s or name
should return a string; you should document when the return type is not obvious.

Examples:

  # valid_url? checks whether the url for a user's homepage is valid. The logic
  # for validity is that the url returned from formatted_url has a host.
  def valid_url?
    ...
  end

  # joined_since? checks if the user has a membership created since the join_date.
  #
  # join_date - A DateTime-like variable used for checking
  def joined_since?(join_date)
    ...
  end

  # name_with_url gives the user's name, optionally linking to the homepage of the user
  # if the user has a homepage and it is valid.
  #
  # Returns an html_safe'd string
  def name_with_url
    ...
  end

  # send_welcome_email sends a welcome email when the user is activated, this is an internal
  # function called by check_for_activation.
  def send_welcome_email
    ...
  end