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?

Answer 1

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:

1. yardoc -q # problem: will suppress useful info too

2. you 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'
   

3. 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