Why is the ":nodoc:" syntax needed?

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.