Commenti interni che utilizzano YARD per la documentazione di Ruby?

Question

Sono in procinto di passare nel corso di un rubygem Io sostengo da RDoc alla documentazione YARD. Tuttavia, ci sono alcuni commenti critici nel codice che hanno bisogno di rimanere solo nel codice e non dovrebbe apparire nella documentazione. Per esempio:

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

onori rdoc il #-- e #++ porte, ma YARD non lo fa. Che (se esiste) è la sintassi per fare una cosa analoga nel markup del cantiere?

Answer 1

Bene, nella sua forma più semplice, rapido e sporco, la soluzione è semplice - basta usare qualsiasi personalizzato (sconosciuto al cantiere) nome del tag. Ad esempio:

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

L'unico problema qui è che cortile vi avvertirà di ogni occorrenza di @internal_note:

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

Credo davvero che ci dovrebbe Be modo ufficiale per sopprimere gli avvertimenti indesiderabili, ma purtroppo non sono riuscito a trovarlo. Tuttavia, si può provare una delle seguenti:

1. yardoc -q # problema: sopprimerà informazioni utili troppo

2. è possibile creare file di yardinit.rb, con il seguente contenuto:

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

   e quindi generare documenti con

   yardoc -e './yardinit.rb'
   

3. C'è un cortile plugin per sopprimere tutti i tag sconosciuto avvertimento https://github.com/ rubyworks / yard-shutup

   non ha un aspetto molto viva, e gem install yard-shutup non funziona, ma è possibile installarlo a mano e fare un tentativo

Answer 2

È possibile scrivere

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

Ed eseguire sulla riga di comando (o metterlo nella tua .yardopts)

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

Answer 3

È possibile utilizzare identation per nascondere o convertito al "commento" in commento cortile:

Esempio 1:

# Show Text1
# Show Text2
# Show Text3

Risultato:

Show Text1
Show Text2
Show Text3

Esempio 2:

# Show Text1
  # Show Text2
  # Show Text3

Risultato:

Show Text2
Show Text3

Esempio 3:

  # Show Text1
# Show Text2
# Show Text3

Risultato:

Show Text2
Show Text3

Esempio 4:

  # Show Text1
# Show Text2
  # Show Text3

Risultato:

Show Text3

Esempio 5:

# Show Text2
  # Show Text1
# Show Text3

Risultato:

Show Text3

Esempio 6:

  # Show Text1
#
  # Show Text3

Risultato:

Show Text3

Esempio 7:

# Show Text2
  #
# Show Text3

Risultato:

Show Text3