Ignore commented out code when using YARD

Question

I have some Ruby code that looks like this:

# some_string = "{really?}"

where the curly braces need to be part of the string. This line is commented out code that I'd like to remain there. I'm additionally using YARD to document code, so when I run yard doc it (naturally) throws a warning about being unable to link "really".

Is there a way I can tell YARD to ignore commented out code?

Answer 1

Is there a way I can tell YARD to ignore commented out code?

On the one hand, YARD is documented as supporting Rdoc markup. And Rdoc is documented to support a couple of ways to hide parts.

RDoc stops processing comments if it finds a comment line starting with -- right after the # character (otherwise, it will be treated as a rule if it has three dashes or more). This can be used to separate external from internal comments, or to stop a comment being associated with a method, class, or module. Commenting can be turned back on with a line that starts with ++.

:stopdoc: / :startdoc:
Stop and start adding new documentation elements to the current container. For example, if a class has a number of constants that you don’t want to document, put a :stopdoc: before the first, and a :startdoc: after the last. If you don’t specify a :startdoc: by the end of the container, disables documentation for the rest of the current file.

Source

On the other hand, I have never persuaded Rdoc or YARD to follow that markup. If your luck is better than mine, you can stop reading here.

If you, too, can't persuade YARD to follow that markup, I think your best bet might be to cut that line, and commit the file with a distinctive commit message--one that you'll be able to find easily by grepping the source control logs.

Finally, rake lets you transform text (code) files in arbitrary ways. You can write a Rakefile to delete lines before processing them through YARD.

$ cat silly-ruby-file.src 
class Something

  def this_method
  end

  def that_method
    # some_string = "{really?}" # Hide me
  end
end

I appended the text # Hide me; it's a lot easier to filter that specific text than it is to filter commented lines of arbitrary code.

$ cat Rakefile
task :default => "silly-ruby-file.rb"
sh "grep -v '# Hide me' silly-ruby-file.src > silly-ruby-file.rb"

This tells rake to run grep, copying all lines except those that have the text "# Hide me" to stdout, which is redirected to "silly-ruby-file.rb".