Es scheint eine Menge von Bibliotheken/Plugins verwendet diese Syntax:Warum wird die Syntax ": nodoc:" benötigt?
def self.included(base) # :nodoc:
base.extend ClassMethods
end
Warum ist der :nodoc: Teil notwendig?
Es ist nicht notwendig. Wenn es auf eine Klasse angewendet wird, unterdrückt es lediglich die Dokumentation (rdoc) für alle Methoden in der Klassenerweiterung. Beschrieben in Programmierung in Ruby als:
: nodoc: - Sie dieses Element nicht enthalten die Dokumentation in . Für Klassen und Module, die Methoden, Aliase, Konstanten und Attribute direkt innerhalb der betroffenen Klasse oder Modul wird auch aus der Dokumentation weggelassen. Standardmäßig werden Module und Klassen innerhalb dieser Klasse oder Module dokumentiert.
Ich glaube nicht, dass es notwendig ist. Meiner Meinung nach ist es eines der nutzlosesten Features von RDoc.
So oft habe ich es beim Lesen eines Codes einer Bibliothek gesehen und musste mich fragen "Warum?". Ich sehe keinen Grund, diese Funktion zu verwenden. Wenn Sie nicht möchten, dass Personen Ihre Methode verwenden, machen Sie sie einfach privat. Das Lesen von Dokumentationen und das Aufrufen eines Methodenaufrufs für eine Methode, die nicht in der Dokumentation enthalten ist, ist ein großer Aufwand.
Sie haben einen Punkt dort. Ich stimme dem nicht zu: 'nodoc:' könnte niemals nützlich sein. Aber es wird überstrapaziert, die Leute neigen dazu, es für Methoden zu verwenden, die sie irgendwie als "unwichtig" betrachten, oder als eine Möglichkeit, der Dokumentation zu entkommen, wenn sie nicht darüber nachdenken können, was sie schreiben sollen. –
Ironischerweise sind Methoden, die als "unwichtig" betrachtet werden, die, bei denen ich mir den Kopf darüber zerbringe, warum ich das mache? Für diese ': nodoc:' ist ein Code (Dokumentation?) Geruch ... –