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?

Fireman

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

Spermatic

Thanks, that solves my problem. Sorry it took me so long to accept! Interesting approach and creative solution, thanks. – Fireman

Answer 2

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

Clarhe

Answer 3

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

Yvonneyvonner