Bug #6381: Useful methods like included don't appear in RDoc

• Status: Third Party's Issue
• Assignee: drbrain (Eric Hodel)
• Target version: -
• ruby -v: ruby 1.9.1p378 (2010-01-10 revision 26273) [i386-mingw32]

[agrimm (Andrew Grimm)]

=begin
Methods like (({Module.included})) and (({Module.private_constant})) don't appear in ruby-doc.org's documentation, because they are private methods. This can cause difficulty for new users of Ruby, for example in http://stackoverflow.com/q/10369876/38765

While there is a rationale behind not showing some private methods, because they are implementation details that should not be relied upon by users of Ruby, this isn't the case here.

This issue has been discussed in ruby-core:40662 and elsewhere, but is something that needs to be put in a bug tracker.
=end

[mame (Yusuke Endoh)]

• Status changed from Open to Rejected
• Assignee set to drbrain (Eric Hodel)

Eric, who is a RDoc maintainer, has already answered [ruby-core:40663] and [ruby-core:40679].
Ruby-doc admin seems to misinterpret Ruby's private as Java's.

I'm sympathetic to your situation. You are between two fires.
Please reopen the ticket if there is any new information.

--
Yusuke Endoh [e-mail]

Dne 3.5.2012 6:23, mame (Yusuke Endoh) napsal(a):

Issue #6381 has been updated by mame (Yusuke Endoh).

Status changed from Open to Rejected
Assignee set to drbrain (Eric Hodel)

Eric, who is a RDoc maintainer, has already answered [ruby-core:40663] and [ruby-core:40679].
Ruby-doc admin seems to misinterpret Ruby's private as Java's.

I'm sympathetic to your situation. You are between two fires.
Please reopen the ticket if there is any new information.

Referring to the same thread as you are pointing, you would find
[ruby-core:40677] and this ticket [1] on rubyforge where Ryan Davis,
RDoc committer, attests that this is RDoc issue.

Vit

[1]
http://rubyforge.org/tracker/index.php?func=detail&aid=28931&group_id=126&atid=575

[mame (Yusuke Endoh)]

• Status changed from Rejected to Assigned

Thanks for letting me know. Eric, what do you think?

--
Yusuke Endoh [e-mail]

[drbrain (Eric Hodel)]

• Status changed from Assigned to Third Party's Issue

=begin
Documentation for Module.included is displayed by using ri generated from 1.9.3:

$ ~/.multiruby/install/1.9.3-p125/bin/ri Module.included
Module.included

(from ruby core)

So the display of documentation for Module.included is not an issue of ruby.

I added directives to pick up documentation for private_constant and public_constant for trunk:

$ ri Module.public_constant
Nothing known about Module.public_constant
$ ri --no-standard -d .ext/rdoc/ Module.public_constant
Module.public_constant

(from .../ruby/trunk/.ext/rdoc)

I have no control over how documentation is generated for uses beyond the built-in ri data such as http://ruby-doc.org, so I will close this as a "third party issue". You should follow up with the contact email at the bottom of http://ruby-doc.org: [e-mail]

=end

[jamesbritt (James Britt)]

=begin
I'm the one running ruby-doc.org. I think there is some misunderstanding here.

The issues isn't that using the -all flag isn't working for ruby-doc.org. It works fine, were it to be used.

The issue is that using --all exposes too many private methods as part of the published API docs, potentially encouraging people to use them.

Ruby API docs on ruby-doc.org are generated using

 rdoc --op <some_place> -f <some_template> prelude.rb *.c

The '--all' flag is not used. Therefore, methods marked as private are not shown. For the most part this is fine (if one agrees that people looking up docs should not be dealing with private methods). The problem is that there are some methods that are marked private but their use case is more akin to public because of the context in which they are used. For example, Module#attr_accessor.

Currently, in order to get the docs for attr_accessor to appear, the rdocs need to be generated using the --all flag. This works, but also exposes every other private method (excluding anything marked with :nodoc:)

What's been requested is a way to mark a method as "private but exposed in rdoc output by default."

If that's already in place, then I'm doing something wrong and welcome any clarification.

If not, I see a few options:

1. Leave things as they are, don't use the --all flag on ruby-doc.org (or any other general public docs site). People just won't see docs for assorted oft-used methods.
2. Leave things as they are, use the --all flag on ruby-doc.org (or any other general public docs site). People will see all those methods in Module and Object, and will also see assorted other private methods on other classes, for better or worse.
3. Add a processing directive to rdoc that allows for a distinction between code visibility and rdoc visibility.

It's interest in the latter that I think generated Andrew's initial bug report.

With option 2, if people are concerned that too many private methods are being exposed in the docs, then those responsible for those methods could mark them with :nodoc:. The obvious downside is that there are all sorts of good reasons why such private methods should be viewable in the docs with the --all flag (just maybe not on a general-audience Web site).

It's quite possible the concerns over using the --all flag are just wrong, in which case there's nothing to do but add --all to my site RDoc generation script. I'm generally not a fan of trying to protect people from their own foolishness, but I did discuss this with a few people I trust and the general opinion was to not show private methods.

In the mean time I'm pondering just offering parallel sets of API docs, one of which comes from using the --all flag, with suitable warnings over the possible fragility code based on private methods.
=end

[trans (Thomas Sawyer)]

Actually, I can't understand why anyone would want to hide private methods. As long as they are clearly marked private in the documentation, then there is no confusion and it is to the advantage of the developer, in that he is able to fully follow the execution of a method and thus truly know what it does. Without private methods being documented you can't do this without pulling up original source code.

[drbrain (Eric Hodel)]

=begin
For documentation in ruby, (({:nodoc:})) is used to indicate implementation details and (({private})) is used for access control.

While not all of the standard library hides its implementation details using (({:nodoc:})), the core C-implemented classes do. It would be helpful if ruby-doc.org started moving towards adding ((%--all%)) when building documentation.
=end

[jamesbritt (James Britt)]

"It would be helpful if ruby-doc.org started moving towards adding --all when building documentation."

Easily done (in fact, already done for a parallel set of docs)

The choice to omit --all as a default came from some discussions with members of the Ruby Documentation Project, and it was there that the idea of way to have an additional directive to manage doc visibility of came up. Perhaps, though, the assumption was that too many implementation-centric methods would otherwise get abused.

If :nodoc: is in place to control this then it's simpler to just use --all by default on ruby-doc.org, so that's what I'll do, and problem solved.

Thank you!