Commentaires internes à l'aide YARD pour la documentation Ruby?

Question

Je suis en train de passer sur une rubygem Je maintiens de RDoc à la documentation YARD. Cependant, il y a des commentaires critiques dans le code qui doivent rester uniquement dans le code et ne devrait pas apparaître dans les documents. Par exemple:

##
# 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

honore rdoc les portes de #-- et #++, mais YARD ne fonctionne pas. Qu'est-ce que (si elle existe) est la syntaxe pour faire une chose analogue dans le balisage de YARD?

Answer 1

Eh bien, dans sa plus simple forme rapide et sale, la solution est facile - il suffit d'utiliser un nom d'étiquette personnalisée (inconnue cour). Par exemple:

##
# 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

Le seul problème ici est que la cour vous préviendra chaque occurrence de @internal_note:

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

Je pense vraiment là devrait être de manière officielle pour supprimer les avertissements indésirables, mais malheureusement je ne pouvais pas trouver. Néanmoins, vous pouvez essayer une des options suivantes:

1. yardoc -q # problème: supprimera des informations utiles aussi

2. vous pouvez créer un fichier yardinit.rb, avec le contenu suivant:

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

   et puis générer docs avec

   yardoc -e './yardinit.rb'
   

3. il y a une cour plug-in pour supprimer toute balise d'avertissement inconnu https://github.com/ rubyworks / cour-shutup

   il ne semble pas très vivant, et gem install yard-shutup ne fonctionne pas, mais vous pouvez l'installer manuellement et essayer

Answer 2

Vous pouvez écrire

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

Et courir sur la ligne de commande (ou la mettre dans votre .yardopts)

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

Answer 3

Vous pouvez utiliser pour masquer ou indentation converti à « commentaire » dans le commentaire de la cour:

Exemple 1:

# Show Text1
# Show Text2
# Show Text3

Résultat:

Show Text1
Show Text2
Show Text3

Exemple 2:

# Show Text1
  # Show Text2
  # Show Text3

Résultat:

Show Text2
Show Text3

Exemple 3:

  # Show Text1
# Show Text2
# Show Text3

Résultat:

Show Text2
Show Text3

Exemple 4:

  # Show Text1
# Show Text2
  # Show Text3

Résultat:

Show Text3

Exemple 5:

# Show Text2
  # Show Text1
# Show Text3

Résultat:

Show Text3

Exemple 6:

  # Show Text1
#
  # Show Text3

Résultat:

Show Text3

Exemple 7:

# Show Text2
  #
# Show Text3

Résultat:

Show Text3