Forum: Ruby-core Relevant methods not appearing in RDoc

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?

Andrew

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.

On Wed, Nov 2, 2011 at 9:55 AM, Eric Hodel <drbrain@segment7.net> wrote:
>
Thanks for that. I've forwarded this thread to the ruby-doc.org email 
address.

Andrew

On Wed, Nov 2, 2011 at 10:05 AM, Andrew Grimm <andrew.j.grimm@gmail.com> 
wrote:
>> 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

Dne 2.11.2011 1:38, Andrew Grimm napsal(a):
>>> I don't know if James Britt (the ruby-doc.org maintainer) is on this mailing 
list.
> Ruby Mendicant University's doc project.
> so commonly used in general code; the usual private method is private
> I tried adding :doc: to the source code in object.c and re-creating
>
I had risen similar questions on various places before:

https://github.com/lsegal/yard/issues/252
http://rubyforge.org/tracker/index.php?func=detail...
http://rubyforge.org/tracker/index.php?func=detail...


Vit

On Nov 1, 2011, at 5:38 PM, Andrew Grimm wrote:
> 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.

private as in "this is an implementation detail" is different from 
private as in "do not call with a receiver"

> 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.

Opting-in to documentation by sprinkling :doc: across various methods to 
fix ruby-doc.org doesn't feel like the right way to go, opting out by 
hiding implementation details feels better.