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?

Heilungkiang

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.

Validity

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.

Bull

You have a point there. I do not agree that :nodoc: could never ever be useful. But it is overused, people tend to use it for methods they consider somehow "unimportant", or as a way to escape writing documentation when they can't think about what to write. – Corson

Ironically methods that are considered "unimportant" are usually the ones I'm scratching my head about thinking "why does it do that?". For those :nodoc: is a code (documentation?) smell... – Gamali

Sometimes a method has to be public so that it is accessible from other modules within the same library, but it is intended to be private to users of the library. Ruby doesn't have a way of expressing that particular amount of privacy, so :nodoc: could be used for that. I'm not sure if that's how its intended to be used. – Carmancarmarthen