Warum ist die „: nodoc:“ Syntax benötigt?

Question

Es scheint, viele Bibliotheken / Plugins verwenden Sie folgende Syntax:

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

Warum ist der :nodoc: Teil notwendig?

Answer 1

Es ist nicht notwendig. Wenn auf eine Klasse angewendet wird, unterdrückt sie nur Dokumentation (rdoc) für alle Methoden in der Klasse-Erweiterung. Beschrieben in Programmierung in Ruby als:

  

: nodoc: -   Fügen Sie keine dieses Element in   die Dokumentation. Für die Klassen und   Module, die Methoden, Aliase   Konstanten und Attribute direkt   innerhalb der betroffenen Klasse oder Modul   wird auch von der weggelassen werden   Dokumentation. In der Standardeinstellung, obwohl,   Module und Klassen innerhalb dieser Klasse   oder Modul dokumentiert werden.

Answer 2

Ich glaube nicht, es ist notwendig. Eigentlich, meiner Meinung nach, ist es eine der nutzlosen Funktionen von RDoc.

So oft ich habe es gesehen, während ein libarie des Code zu lesen und ich musste mich fragen: „Warum?“. Ich sehe keinen Grund, diese Funktion zu nutzen. Wenn Sie Ihre Methode verwenden, die Menschen nicht wollen, nur machen es privat. Es ist ein großer Aufwand, wenn Dokumentation zu lesen und einen Methodenaufruf auf ein Verfahren zu sehen, die aus der Dokumentation noch übrig sind.