Where is my :nodoc:?
Rubydoc.info uses
YARD for all of its documentation generation. 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.
The @private Tag
Fortunately, YARD has a few alternatives to :nodoc:
that allow you to benefit from powerful documentation while
trimming down on certain unwanted details. YARD has a meta-data
based "tag style" formatting, and has a @private tag
that can be applied to any documentable element. This marks the
element as having "private" visibility, and is meant to be used
when the element cannot be marked as private (because it is a
class/module/constant or other non-method object).
How to Use @private
Note that this tag alone does not hide the object from your
documentation. You need to also specify --no-private
(not --private) in your .yardopts
file (see how
to setup a .yardopts file here). This is done to ensure that
@private is not used as a "drop-in" replacement for
:nodoc:. The extra step is intentional, and we want
you to take this time to reflect on why you are hiding information
from your documentation.
When to Use @private
The @private tag is simply meant to fill the
visibility gap that is currently missing from Ruby for
constants.
It is not recommended practice to overuse @private,
and is generally never acceptable for use with methods (since they
can be marked as private quite easily). In general, you should only
use this tag to hide internal classes that can
never be used externally. However, carefully note the
connotation of the term "private" versus "nodoc". We still want you
to think about documenting these objects, since they might be
valuable to an internals API! By marking an object as private, you
should not be saying "I will not document this", you should be
saying that the documentation for the object is not meant for
public consumption.
Also note that Ruby 1.9.3 will introduce the concept of private
constants, and @private might eventually disappear
completely.