ruby - Ruby ドキュメントに YARD を使用した内部コメント?

Question

私は、管理している ruby​​gem を 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 は#--and#++ゲートを尊重しますが、YARD は受け入れません。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次の内容のfile を作成できます。

   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

identation を使用して、庭のコメントを非表示にしたり、「コメント」に変換したりできます。

例 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