22

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?

scable
  • 4,064
  • 1
  • 27
  • 41
Bryan Locke
  • 2,337
  • 5
  • 25
  • 30

2 Answers2

26

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.

Svante
  • 50,694
  • 11
  • 78
  • 122
Chirantan
  • 15,304
  • 8
  • 49
  • 75
3

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.

Patrik
  • 95
  • 9
  • 1
    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. – Boris Stitnicky Oct 20 '14 at 23:51
  • 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... – Luca Spiller Apr 11 '16 at 12:48
  • 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. – cambunctious Aug 01 '23 at 14:34