Forum: Ruby docstrings

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Bec38d63650c8912b6ba9b557fb953b9?d=identicon&s=25 Roger Pack (rogerdpack)
on 2009-02-12 00:03
I like docstrings for being able to know what dynamically generated
methods do.
For instance, in rails, there is no documentation for

People.find_by_first_name # it's obvious, but--there is nothing in the
ri to lookup for it.  Is it case sensitive?  Does it assume defaults for
the other values?

I'd like to suggest docstrings as a nice way to be able to track those.
Especially methods that were created using eval--they are
documentationless.

However, at the same time, now that we have Proc#owner, it would be
possible to "fake it" via something like

module_eval
"@method_name_description = 'a description of the method--it searches
for all instances with a first_name of param1, default to george'
def find_by_first_name
 # stuff
end
"

There's also "fastri+irb" which works for non dynamic methods [1], and
also you can lookup the source for non dynamic methods using
#source_location and SCRIPT_LINES__

I was about to make a suggestion to the core fellas to consider
docstrings.
Thoughts on my suggestion?
Thanks much!
-=roger
[1] http://eigenclass.org/hiki/irb+ri+completion
8f6f95c4bd64d5f10dfddfdcd03c19d6?d=identicon&s=25 Rick Denatale (rdenatale)
on 2009-02-12 13:37
(Received via mailing list)
On Wed, Feb 11, 2009 at 6:01 PM, Roger Pack <rogerpack2005@gmail.com>
wrote:

> I like docstrings for being able to know what dynamically generated
> methods do.
> For instance, in rails, there is no documentation for
>
> People.find_by_first_name # it's obvious, but--there is nothing in the
> ri to lookup for it.  Is it case sensitive?  Does it assume defaults for
> the other values?


I guess by docstrings  you mean Python docstrings, yes?

I may be dense, but I'm not sure I see any difference in power here from
what's provided by rdoc comments, which are effectively the Ruby version
of
docstrings. They might be terser, but they effectively serve the same
role
as far as I can tell.

Since docstrings, like rdoc comments have to appear in the source code,
I
don't understand how they help documenting code which is dynamically
generated when the program is run.

In my current project, I recently switched over from dynamicly defined
methods to a rake task to generate some of the source code in order to
have
the resulting methods documented with RDOC/RI.

--
Rick DeNatale

Blog: http://talklikeaduck.denhaven2.com/
Twitter: http://twitter.com/RickDeNatale
Bec38d63650c8912b6ba9b557fb953b9?d=identicon&s=25 Roger Pack (rogerdpack)
on 2009-02-12 18:50
> Since docstrings, like rdoc comments have to appear in the source code,
> I
> don't understand how they help documenting code which is dynamically
> generated when the program is run.
>
> In my current project, I recently switched over from dynamicly defined
> methods to a rake task to generate some of the source code in order to
> have
> the resulting methods documented with RDOC/RI.

I do like the current ri style, and it does 90% of what I'm asking for.

So the question is what benefit is gained with dynamic documentation
over ri style comments?

The two goals I'd have are 1) quick lookup from irb
Ex:
Currently ruby does not have a
method.desc
command.

and also documentation for dynamically generated methods.  As you noted
above, it requires extra work.  Rails, for example, cannot enumerate all
its possible dynamic methods.

Is there a way in rdoc to describe dynamically generated methods?

The first goal is the most important, now that I think about it.

I could create a gem which include "irb fastri" lookup [1].

Am I missing anything?
-=r
[1] http://eigenclass.org/hiki/irb+ri+completion
8f6f95c4bd64d5f10dfddfdcd03c19d6?d=identicon&s=25 Rick Denatale (rdenatale)
on 2009-02-12 19:12
(Received via mailing list)
On Thu, Feb 12, 2009 at 12:48 PM, Roger Pack
<rogerpack2005@gmail.com>wrote:

>
>
See below


>
> and also documentation for dynamically generated methods.  As you noted
> above, it requires extra work.  Rails, for example, cannot enumerate all
> its possible dynamic methods.
>
> Is there a way in rdoc to describe dynamically generated methods?


I don't think so, perhaps Eric Hodel can confirm or deny this.

>
>
> The first goal is the most important, now that I think about it.
>
> I could create a gem which include "irb fastri" lookup [1].


No need to create a gem, you just put the code from the eigenclass
article
into ~/.irbrc and bob's yer uncle.

>
> -=r
> [1] http://eigenclass.org/hiki/irb+ri+completion
>
>

--
Rick DeNatale

Blog: http://talklikeaduck.denhaven2.com/
Twitter: http://twitter.com/RickDeNatale
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2009-02-25 20:47
(Received via mailing list)
On Feb 12, 2009, at 10:08, Rick DeNatale wrote:

>> Is there a way in rdoc to describe dynamically generated methods?
>
> I don't think so, perhaps Eric Hodel can confirm or deny this.

Since RDoc 2.2 I think:

ri RDoc::Parser::Ruby
This topic is locked and can not be replied to.