Hiding a method from YARD (the right way)

Question

I am using YARD to document one of my Ruby projects. I have certain methods that I do not want to be included in the documentation, things like #inspect and #to_s that you expect to exist and return a reasonable result.

It is possible to hide these methods using the @private tag and the yardoc --no-private command-line option:

# @private let's not document this
def inspect; ...; end

However, the YARD documentation on @private explicitly states:

Note: This method is not recommended for hiding undocumented or “unimportant” methods. This tag should only be used to mark objects private when Ruby visibility rules cannot do so.

If I use @api private instead, YARD (nicely) tags the methods with a private badge in the documentation, but still shows them.

Is there a "legal" way to hide methods from YARD output?

Masculine

From the website: "Although YARD is mostly compatible with RDoc, it does not support RDoc "directives" such as :stopdoc: or :nodoc:. There are a few reasons for this, but the most important is that it is very easy to misuse :nodoc:, and this misuse often causes your readers to miss out on vital information in your documentation." I believe what you want to do is intentionally not possible. – Altis

Answer 1

From my limited tests, I noticed the following works well (and doesn't have the explicit note in the documentation to avoid for your use case):

# @!visibility private
def inspect; ...; end

According to the yard documentation:

@!visibility public | protected | private

Modifies the current parsing visibility (public, protected, or private).

Hope that helps.

Pickax

This is the same as labeling every member @private, so the same note applies. The author of Yard simply doesn’t like the idea of changing visibility in documentation because he considers it to be misused. – Shae