Внутренние комментарии с использованием YARD для Ruby документации?

Question

Я нахожусь в процессе переключения rubygem с документации RDoc на YARD.Однако в коде есть некоторые критические комментарии, которые должны оставаться только в коде и не должны отображаться в документации.Например:

##
# 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 соблюдает ворота #-- и #++, а YARD - нет.Каков (если он существует) синтаксис для выполнения аналогичных действий в разметке YARD?

Answer 1

Вы можете написать

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

И запустить в командной строке (или поместить в свой .yardopts)

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

Answer 2

Ну, в простейшем, быстром и грязном виде решение легко - просто используйте любое другое (неизвестное двору) имя тега. Например:

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

Единственная проблема здесь в том, что ярд будет предупреждать вас о каждом появлении @internal_note:

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

Я действительно думаю, что должен быть официальным способом подавления нежелательных предупреждений, но, к сожалению, я не смог его найти. Тем не менее, вы можете попробовать одно из следующих:

1. yardoc -q # проблема: также отключит полезную информацию

2. вы можете создать файл yardinit.rb со следующим содержанием:

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

   , а затем генерировать документы с

   yardoc -e './yardinit.rb'
   

3. есть плагин ярда для подавления всех предупреждений о неизвестных тегах https://github.com/rubyworks/yard-shutup

   выглядит не очень живо, gem install yard-shutup не работает, но вы можете установить его вручную и попробовать

Answer 3

Вы можете использовать идентификацию, чтобы скрыть или преобразовать «комментарий» в комментарии двора:

Пример 1:

# Show Text1
# Show Text2
# Show Text3

Результат:

Show Text1
Show Text2
Show Text3

Пример 2:

# Show Text1
  # Show Text2
  # Show Text3

Результат:

Show Text2
Show Text3

Пример 3:

  # Show Text1
# Show Text2
# Show Text3

Результат:

Show Text2
Show Text3

Пример 4:

  # Show Text1
# Show Text2
  # Show Text3

Результат:

Show Text3

Пример 5:

# Show Text2
  # Show Text1
# Show Text3

Результат:

Show Text3

Пример 6:

  # Show Text1
#
  # Show Text3

Результат:

Show Text3

Пример 7:

# Show Text2
  #
# Show Text3

Результат:

Show Text3