Internal comments using YARD documentation for Ruby?

Question

I move on to the rubigem that I support from the RDoc documentation in YARD. However, there are critical comments in the code that should remain only in the code and should not be displayed 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 rewards gate #-- and #++ , but YARD does not. What (if it exists) is the syntax for similar use in YARD markup?

Answer 1

Well, in its simplest, fastest and most dirty form, the solution is easy - just use any custom (unknown for the yard) tag name. For instance:

 ## # 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 problem here is that the kernel will warn you about every 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 that should be the official way to suppress unwanted warnings, but unfortunately I could not find it. However, you can try one of the following:

• yardoc -q # problem: will also suppress useful information.

• you can create a yardinit.rb file with the following contents:

   YARD::Tags::Library.define_tag('INTERNAL NOTE', :internal_note) 

  and then generate documents using

   yardoc -e './yardinit.rb' 

• there is a yard plugin to suppress all unknown tag warnings https://github.com/rubyworks/yard-shutup

  it doesn’t look very lively and the gem install yard-shutup doesn’t work, but you can install it manually and try to try

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 in your .yardopts )

 $ yard doc --tag comment --hide-tag comment 

Answer 3

You can use identification to hide or transform the "comment" in the comment yard:

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