From: Andrew Grimm <andrew.j.grimm@...>
Date: 2011-11-02T09:38:03+09:00
Subject: [ruby-core:40666] Re: Relevant methods not appearing in RDoc

On Wed, Nov 2, 2011 at 10:05 AM, Andrew Grimm <andrew.j.grimm@gmail.com> wrote:
> On Wed, Nov 2, 2011 at 9:55 AM, Eric Hodel <drbrain@segment7.net> wrote:
>> On Nov 1, 2011, at 3:45 PM, Andrew Grimm wrote:
>>> The method Module.private_constant isn't appearing in
>>> http://www.ruby-doc.org/core-1.9.3/Module.html . Is this because
>>> private_constant is private, and RDoc doesn't document private methods
>>> unless specifically told to with :doc: in the source code or with
>>> --all on the command line?
>>
>> Ruby builds ri documentation with the --all argument, perhaps ruby-doc.org does not?
>>
>> I don't know if James Britt (the ruby-doc.org maintainer) is on this mailing list.
>>
>
> Thanks for that. I've forwarded this thread to the ruby-doc.org email address.
>
> Andrew
>
>

I asked James Britt about this, and this is his reply (forwarded with
permission):

This is being discussed with the maintainers of RDoc and the folks at
Ruby Mendicant University's doc project.


A few people have written to me to say that, for example, the attr_*
methods are not appearing in the ruby-doc API docs. They're private,
but private to Object so they're of course visible where you need
them, so they don't *feel* so private. (In fact I was surprised they
were marked private since their proper usage never gets in the way of
their visibilty.)

They (and a few other methods) are a weird edge case because they are
so commonly used in general code; the usual private method is private
because it is an implementaion detail that could change form one
release to the next, and should not be used in general application
code.


I asked a few people about just having all private methods appear on
ruby-doc (i.e. use the "--all" switch) but the feeling is that it
would end up too cluttered.  Worse, it would likely encourage people
to use those private methods that really are meant to be private.

I tried adding :doc: to the source code in object.c and re-creating
the docs but it didn't work for me; maybe this is a Ruby-source only
directive (or I'm just doing it wrong).  So, for the immediate future,
these methods won't be appearing in the API docs. However it's a known
problem and proper fix for it is being worked on.


Hope this helps clarify things a bit.


James