Internal comments using YARD for Ruby documentation?
Question
I'm in the process of switching over a rubygem I maintain from RDoc to YARD documentation. However, there are some critical comments in the code that need to remain only in the code and should not show up in the documentation. For instance:
##
# 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 honors the #--
and #++
gates, but YARD does not. What (if it exists) is the syntax for doing an analogous thing in YARD's markup?
Solution
Well, in its simplest, quick and dirty form, solution is easy - just use any custom (unknown to yard) tag name. For example:
##
# 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
The only issue here is that yard will warn you about each occurrence of @internal_note:
[warn]: Unknown tag @internal_note in file ... near line xxx
[warn]: Unknown tag @internal_note in file ... near line yyy
...
I really think there should be official way to suppress the undesirable warnings, but unfortunately I couldn't find it. Nevertheless, you may try one of the following:
yardoc -q
# problem: will suppress useful info tooyou may create file
yardinit.rb
, with the following content:YARD::Tags::Library.define_tag('INTERNAL NOTE', :internal_note)
and then generate docs with
yardoc -e './yardinit.rb'
there is a yard plugin to suppress all unknown tag warning https://github.com/rubyworks/yard-shutup
it doesn't look very alive, and
gem install yard-shutup
doesn't work, but you may install it by hand and give it a try
OTHER TIPS
You can write
# @comment TODO: This will not be seen
def method(*args)
...
end
And run on the command line (or put it into your .yardopts
)
$ yard doc --tag comment --hide-tag comment
You can use identation to hide or convert to "comment" in yard comment:
Example 1:
# Show Text1
# Show Text2
# Show Text3
Result:
Show Text1
Show Text2
Show Text3
Example 2:
# Show Text1
# Show Text2
# Show Text3
Result:
Show Text2
Show Text3
Example 3:
# Show Text1
# Show Text2
# Show Text3
Result:
Show Text2
Show Text3
Example 4:
# Show Text1
# Show Text2
# Show Text3
Result:
Show Text3
Example 5:
# Show Text2
# Show Text1
# Show Text3
Result:
Show Text3
Example 6:
# Show Text1
#
# Show Text3
Result:
Show Text3
Example 7:
# Show Text2
#
# Show Text3
Result:
Show Text3