Dokumentieren Parameter für Makro generierten Methoden mit YARD

Question

Geben Sie die folgende Eingabe:

class A 
    # @!macro [attach] add_setting 
    # @!attribute [rw] $1 
    # @!method $1=(value) 
    def self.add_setting(setting) 
    end 

    # @param value [String] Hexadecimal representation of color 
    add_setting :color 
end 

YARD 0.9.12 die folgende Warnung erzeugt (neu seit ~> 0,8):

[warn]: @param tag has unknown parameter name: value 
    in file `test.rb' near line 9 

Was die richtige ist Möglichkeit, diese Dokumentation zu strukturieren, um die Warnung zu vermeiden? (Dieses Muster wird in rspec verwendet.)

Answer 1

Sie sind richtig, dass rspec diese Dokumentation verwendet, und Sie können sehen, dass sie die macro

# @macro [attach] add_setting 
# @!attribute [rw] $1 
# @!method $1=(value) 
# ..... 
# @macro add_setting 
# Run examples over DRb (default: `false`). RSpec doesn't supply the DRb 
# server, but you can use tools like spork. 
add_setting :drb 

definiert angeben Verwendung Wenn Sie feststellen, die @macro add_setting Erklärung dieses yard sagt, wenn die Dokumentation Diese Methode verwenden Sie die add_settingmacro. In diesem Fall bedeutet $1drb, also dokumentiert es das drb Attribut. (nicht die einzelnen Getter/Setter-Methoden)

Wie Sie sehen können, wenn sie diese Methoden dokumentieren, deklarieren sie keinen Datentyp, weil diese Typen für die verschiedenen dokumentierten Methoden unterschiedlich sein können. Stattdessen geben sie den Standardwert in der Beschreibung der Methode an.

Option 1 (nicht sicher, warum es funktioniert)

einfach die Getter und Setter definieren anstatt !@attribute Erklärung, die wie

class A 
    # @!macro [attach] add_setting 
    # @!method $1 
    #  @return [Object] the $1 of the a 
    # @!method $1=(value) 
    def self.add_setting(setting) 
    end 
    # @param value [String] Hexadecimal representation of color 
    add_setting :color 
end 

aussehen würde die @return ist wichtig, oder die Warnung kommt zurück

Option 2

Wenn Sie wirklich diese Funktionalität wollten Sie @overload verwenden könnte, die wie

class A 
    # @!macro [attach] add_setting 
    # @!method $1 
    #  @return [Object] the $1 of the a 
    # @!method $1=(value) 
    def self.add_setting(setting) 
    end 
    # @overload color=(value) 
    # @param value [String] Hexadecimal representation of color 
    # @macro add_setting 
    add_setting :color 
    add_setting :name 
end 

Dies bewirkt, dass die Getter-Methode für name und color zu dokumentieren, wie aussehen:

• name => Objekt
  • Gibt den Namen der a
zurück =
• Farbe> Objekt
  • Gibt die Farbe des a

aber die Setter-Methoden wie

• name = (Wert) => Objekt
aussehen
• Farbe = (Wert) => Objekt
  • Parameter:
  • Wert (String) - hexadezimale Darstellung Farbe

weil wir color= überlastet.

Das heißt, das hilft Ihnen nicht wirklich, da es wahrscheinlich darin bestehen würde, die Methoden trotzdem einzeln zu dokumentieren.

Weitere Optionen:

• Ignorieren Sie die Warnungen
• ziemlich alle Warnungen vollständig -q
• Kasse diese Thread