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

Question

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

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

Answer 1

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

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

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

Answer 2

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

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

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

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

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