Interne Kommentare Verwenden von Yards für Ruby -Dokumentation?

Question

Ich bin gerade dabei, einen Rubygem zu wechseln, den ich von RDOC bis Hofdokumentation unterhalte. Es gibt jedoch einige kritische Kommentare im Code, die nur im Code bleiben müssen und nicht in der Dokumentation angezeigt werden sollten. Zum Beispiel:

##
# SomeClass documentation here.
#--
# CRITICAL comment that should be in the code but not in the documentation,
#          and must be at this particular spot in the code.
#++
# more documentation that follows the critical comment block, but this part 
# should be in the generated documentation
class SomeClass
    ...
end

Rdoc ehrt die #-- und #++ Tore, aber der Hof nicht. Was (wenn es existiert) ist die Syntax für eine analoge Sache in Yards Markup?

Answer 1

Nun, in seiner einfachsten, schnellen und schmutzigen Form ist Lösung einfach - verwenden Sie einfach einen benutzerdefinierten (unbekannten Yard) -Tagnamen. Zum Beispiel:

##
# SomeClass documentation here.
#
# @internal_note CRITICAL
#   comment that should be in the code but not in the documentation,
#   and must be at this particular spot in the code.
#
# more documentation that follows the critical comment block, but this part 
# should be in the generated documentation

Das einzige Problem hier ist, dass Yard Sie vor jedem Ereignis von @Internal_note warnen wird:

[warn]: Unknown tag @internal_note in file ... near line xxx
[warn]: Unknown tag @internal_note in file ... near line yyy
...

Ich denke wirklich dort sollte Seien Sie offizieller Weg, um die unerwünschten Warnungen zu unterdrücken, aber leider konnte ich es nicht finden. Trotzdem können Sie eines der folgenden versuchen:

1. yardoc -q # Problem: unterdrückt auch nützliche Informationen

2. Sie können Datei erstellen yardinit.rb, mit dem folgenden Inhalt:

   YARD::Tags::Library.define_tag('INTERNAL NOTE', :internal_note)
   

   und erzeugen dann Dokumente mit

   yardoc -e './yardinit.rb'
   

3. Es gibt ein Yard -Plugin, um alle unbekannten Tag -Warnung zu unterdrücken https://github.com/rubyworks/yard-shutup

   es sieht nicht sehr lebendig aus und gem install yard-shutup Funktioniert nicht, aber Sie können es von Hand installieren und es versuchen

Answer 2

Du kannst schreiben

# @comment TODO: This will not be seen
def method(*args)
  ...
end

Und laufen Sie auf der Befehlszeile (oder geben Sie sie in Ihre .yardopts)

$ yard doc --tag comment --hide-tag comment

Answer 3

Sie können Identation verwenden, um im Yard -Kommentar zu verbergen oder in "Kommentar" zu konvertieren:

Beispiel 1:

# Show Text1
# Show Text2
# Show Text3

Ergebnis:

Show Text1
Show Text2
Show Text3

Beispiel 2:

# Show Text1
  # Show Text2
  # Show Text3

Ergebnis:

Show Text2
Show Text3

Beispiel 3:

  # Show Text1
# Show Text2
# Show Text3

Ergebnis:

Show Text2
Show Text3

Beispiel 4:

  # Show Text1
# Show Text2
  # Show Text3

Ergebnis:

Show Text3

Beispiel 5:

# Show Text2
  # Show Text1
# Show Text3

Ergebnis:

Show Text3

Beispiel 6:

  # Show Text1
#
  # Show Text3

Ergebnis:

Show Text3

Beispiel 7:

# Show Text2
  #
# Show Text3

Ergebnis:

Show Text3