Forum: Ruby-core Relevant methods not appearing in RDoc

01bbb59a1c3ef9960f25a97afe7e920f?d=identicon&s=25 Andrew Grimm (Guest)
on 2011-11-01 23:46
(Received via mailing list)
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
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2011-11-01 23:56
(Received via mailing list)
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.
01bbb59a1c3ef9960f25a97afe7e920f?d=identicon&s=25 Andrew Grimm (Guest)
on 2011-11-02 00:05
(Received via 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
01bbb59a1c3ef9960f25a97afe7e920f?d=identicon&s=25 Andrew Grimm (Guest)
on 2011-11-02 01:39
(Received via mailing list)
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
0930ba88f6a56b4fb041590a4e83e845?d=identicon&s=25 "Vít Ondruch" <v.ondruch@gmail.com> (Guest)
on 2011-11-02 18:22
(Received via mailing list)
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
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2011-11-02 20:48
(Received via mailing list)
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.
This topic is locked and can not be replied to.