Rubyドキュメントにヤードを使用した内部コメント？

Question

私はRDOCからヤードのドキュメントに維持しているRubyemを切り替える過程にあります。ただし、コードにはコードにのみ留まる必要があり、ドキュメントに表示されるべきではない重要なコメントがいくつかあります。例えば：

##
# 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が尊重します #-- と #++ ゲートですが、庭はそうではありません。ヤードのマークアップで類似のことをするための構文は何ですか？

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

   それはあまり生きていないように見えません 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