Pourquoi le « : nodoc: » syntaxe nécessaire?

Question

Il semble que beaucoup de bibliothèques / plugins utilisent cette syntaxe:

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

Pourquoi la partie :nodoc: nécessaire?

Answer 1

Il ne faut pas. Si elle est appliquée à une classe, il supprime simplement la documentation (rdoc) pour toutes les méthodes de l'extension de classe. Décrite dans la programmation Ruby comme:

  

: nodoc: -   Ne pas inclure cet élément dans   La documentation. Pour les classes et   modules, les méthodes, les alias,   les constantes et les attributs directement   au sein de la classe concernée ou d'un module   sera omis aussi   Documentation. Par défaut, cependant,   modules et des classes au sein de cette classe   ou le module sera documenté.

Answer 2

Je ne pense pas qu'il soit nécessaire. En fait, à mon avis, il est l'une des caractéristiques les plus inutiles de RDoc.

Tant de fois je l'ai vu en lisant le code d'un libarie et je devais me demander « Pourquoi? ». Je ne vois aucune raison d'utiliser cette fonctionnalité. Si vous ne voulez pas que les gens utilisent votre méthode, juste le rendre privé. Il est un grand tracas lors de la lecture des documents et de voir un appel de méthode à une méthode qui reste de la documentation.