Porque é que a “: nodoc:” sintaxe necessária?

Question

Parece um monte de bibliotecas / plugins usar esta sintaxe:

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

Por que é a parte :nodoc: necessário?

Answer 1

Não é necessário. Se aplicado a uma classe, apenas suprime a documentação (rdoc) para todos os métodos na extensão de classe. Descrito na programação Ruby como:

: nodoc: - Não incluir este elemento no a documentação. Para as classes e módulos, os métodos, os pseudónimos, constantes e atributos directamente dentro da classe ou módulo afectado também será omitido do documentação. Por padrão, no entanto, módulos e classes dentro dessa classe ou módulo será documentado.

Answer 2

Eu não acho que seja necessário. Na verdade, na minha opinião, é uma das características mais inúteis de RDoc.

Por muitas vezes eu vi isso durante a leitura de código de um libarie e eu tive que me perguntar "Por quê?". Não vejo qualquer razão para usar esse recurso. Se você não quer que as pessoas a usar seu método, apenas torná-lo privado. É uma grande confusão quando a documentação lendo e vendo uma chamada de método para um método que é deixado de fora da documentação.