Documenting hooks

The coolest hook is useless without documentation. So, always remember, if you introduce hooks in your classes, do write about it. It is a part of your API, so document it.

• Place documentation either in the README directly, or in the header part of your main class
• Title it “Hooks” or “Filters” (filters seems to be more attractive to many people, although it’s the wrong word)

Always define the

• hook name
• rough place where the hook is run
• parameters that are passed

Example

Imagine we had the following setup.

class Tweet
  define_hook :after_initialize
  
  def initialize(text)
    # ... tweet the shit.
    run_hook :after_initialize, self
  end

So Rdoc could look like this.

== Hooks
<b>after_initialize</b>:: Run at the very end of +initialize+. Receives +self+.

This is almost enough, but will greatly improve your API understandings.