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.

Answer 2

I don't think it's necessary. Actually, in my opinion, it's one of the most useless features of RDoc.

So many times I've seen it while reading a libarie's code and I had to ask myself "Why?". I don't see any reason to use this feature. If you don't want people to use your method, just make it private. It's a big hassle when reading documentation and seeing a method call to a method that's left out of the documentation.