¿Comentarios internos usando el patio para la documentación de Ruby?

Question

Estoy en el proceso de cambiar sobre un Rubygem que mantengo de la documentación de RDOC a Yard. Sin embargo, hay algunos comentarios críticos en el código que deben permanecer solo en el código y no deben aparecer en la documentación. Por ejemplo:

##
# 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 honra el #-- y #++ Gates, pero Yard no. ¿Qué (si existe) es la sintaxis para hacer algo análogo en el marcado de Yard?

Answer 1

Bueno, en su forma más simple, rápida y sucia, la solución es fácil: solo use cualquier nombre de etiqueta personalizado (desconocido para patio). Por ejemplo:

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

El único problema aquí es que el patio le advertirá sobre cada ocurrencia de @Internal_Note:

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

Realmente creo que ahí debería Sea una forma oficial de suprimir las advertencias indeseables, pero desafortunadamente no pude encontrarla. Sin embargo, puede probar uno de los siguientes:

1. yardoc -q # Problema: suprimirá la información útil también

2. puede crear archivo yardinit.rb, con el siguiente contenido:

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

   y luego generar documentos con

   yardoc -e './yardinit.rb'
   

3. Hay un complemento de patio para suprimir toda advertencia de etiqueta desconocida https://github.com/rubyworks/yard-shutup

   No se ve muy vivo y gem install yard-shutup no funciona, pero puede instalarlo a mano y probarlo

Answer 2

Puedes escribir

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

Y ejecute en la línea de comando (o póngalo en tu .yardopts)

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

Answer 3

Puede usar la identación para esconder o convertir a "comentarios" en el comentario del patio:

Ejemplo 1:

# Show Text1
# Show Text2
# Show Text3

Resultado:

Show Text1
Show Text2
Show Text3

Ejemplo 2:

# Show Text1
  # Show Text2
  # Show Text3

Resultado:

Show Text2
Show Text3

Ejemplo 3:

  # Show Text1
# Show Text2
# Show Text3

Resultado:

Show Text2
Show Text3

Ejemplo 4:

  # Show Text1
# Show Text2
  # Show Text3

Resultado:

Show Text3

Ejemplo 5:

# Show Text2
  # Show Text1
# Show Text3

Resultado:

Show Text3

Ejemplo 6:

  # Show Text1
#
  # Show Text3

Resultado:

Show Text3

Ejemplo 7:

# Show Text2
  #
# Show Text3

Resultado:

Show Text3