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] eigenclass.org
On Thu, Feb 12, 2009 at 12:48 PM, Roger P.
[email protected]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 H. 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] eigenclass.org
–
Rick DeNatale
Blog: http://talklikeaduck.denhaven2.com/
Twitter: http://twitter.com/RickDeNatale
On Wed, Feb 11, 2009 at 6:01 PM, Roger P. [email protected]
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
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] eigenclass.org
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 H. can confirm or deny this.
Since RDoc 2.2 I think:
ri RDoc::Parser::Ruby