Although not recommended, use @Private and --no-private with yardoc or @api to declare your public/private api and --query to expose them. :nodoc: is generally a bad documentation habit, as that implies you are not documenting the specific method/module/class. This should ideally never be the case. Practically of course there are some cases where certain objects may be less important to your public API, but they should only be hidden in those contexts. :nodoc: fails to capture this semantic, where @Private does. Also realize that hiding methods that are available to a programmer may make their lives more difficult and defeats the purpose of documentation. I won't claim to know your use case (there is a small handful of useful use cases for @Private), but you should tread lightly if your habit is to :nodoc: every object you're personally uninterested in.

More here: http://yardoc.org/docs/yard/file:docs/WhatsNew.md

Thanks for pointing out @Private. I agree with your position, but there is one situation that can arise in OO languages where something like :nodoc: is appropriate: internal protocols. Sometimes, two objects within a module need to cooperate in some special way, e.g. in FFI bindings some object implements #to_ptr to return its underlying FFI::Pointer representation, but the implementer wishes to hide the bindings' FFI underpinnings completely.

In a language like Haskell, this problem doesn't exist because it's possible to pick and choose which methods a module should export, regardless of what types they operate on, and Haskell documentation tools only cover exported functions. Some OO languages support friend types, allowing related data types to share private methods. In a simpler type system like Ruby's, :nodoc: (and @Private) is the best we can do.

Best,

Jeremy

I certainly understand the internal protocol use case. That's pretty much why @Private exists, to try and make Ruby's visibilities more granular than they are. :nodoc: is a little different though, because even internal protocols should have some form of documentation (ideally)-- using :nodoc: implies no documentation, which can occasionally be extremely unhelpful, even for methods that are not part of a "public" API. Many Ruby projects have poor documentation because they abuse that functionality; YARD's trying to change that behaviour.

But yea, if your use case is the internal protocol deal then @Private is exactly what you should use.

Regards,

Loren

I was looking for this functionality because my classes override some methods from Object (like #inspect and #to_s) and I didn't want those functions to show up in the documentation. Not the most important thing in the world though.