docstrings

[Roger Pack]

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

 

[Rick DeNatale]

[Note: parts of this message were removed to make it a legal post.]

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.

 

[Roger Pack]

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

 

[Rick DeNatale]

[Note: parts of this message were removed to make it a legal post.]

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.

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

 

[Eric Hodel]

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

Since RDoc 2.2 I think:

ri RDoc:arser::Ruby