From: "Vít Ondruch" <v.ondruch@...>
Date: 2011-11-03T02:21:15+09:00
Subject: [ruby-core:40677] Re: Relevant methods not appearing in RDoc

Dne 2.11.2011 1:38, Andrew Grimm napsal(a):
> 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
>

I had risen similar questions on various places before:

https://github.com/lsegal/yard/issues/252
http://rubyforge.org/tracker/index.php?func=detail&aid=28931&group_id=126&atid=575
http://rubyforge.org/tracker/index.php?func=detail&aid=29047&group_id=627&atid=2472


Vit