Question

It seems a lot of libraries/plugins use this syntax:

  def self.included(base) # :nodoc:
    base.extend ClassMethods
  end

Why is the :nodoc: part necessary?

Answer 1

It is not necessary. If applied to a class, it just suppresses documentation (rdoc) for all the methods in the Class extension. Described in Programming Ruby as:

:nodoc: –
Don’t include this element in
the documentation. For classes and
modules, the methods, aliases,
constants, and attributes directly
within the affected class or module
will also be omitted from the
documentation. By default, though,
modules and classes within that class
or module will be documented.