Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Missing support for RDoc's :nodoc: tag #34

Closed
jvoorhis opened this issue Nov 8, 2009 · 4 comments

Comments

@jvoorhis
Copy link

commented Nov 8, 2009

There seems to be no easy way to suppress Ruby certain code objects from appearing in generated docs. If it's easier to support this using a tag such as `@Nodoc', that would be a fine solution.

@lsegal

This comment has been minimized.

Copy link
Owner

commented Nov 15, 2009

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

@jvoorhis

This comment has been minimized.

Copy link
Author

commented Nov 17, 2009

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

@lsegal

This comment has been minimized.

Copy link
Owner

commented Nov 17, 2009

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

@Hubro

This comment has been minimized.

Copy link

commented Nov 10, 2014

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.

This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.