Enhance Proc docs
What caught me recently while mentoring students: there is almost no "canonical" explanation about procs in Ruby's core docs: Nothing in
doc/*.rdoc, and for the
Proc class, documentation of what it is and what it does is pretty spartan.
I am trying to fix this by adding to
Proc class header documentation.
- More friendly and detailed explanation of the whole concept.
- Different methods of creating lambda and non-lambda procs.
- Lambda semantics.
- Conversion to proc from other objects and
About (3): currently, Proc docs do have an explanation about it, but there are two problems:
- it all placed in docs for predicate method
#lambda?(like nobody should be interested in the concept unless uses this method);
- from my perspective, it uses pretty unfortunate wording: instead of talking about proc object semantics, it calls non-lambdas behavior "tricks", and informally tells about "procs with tricks"/"procs without tricks".
If my class documentation would be accepted, I propose to cut the explanations in
#lambda? method down to a one-liner ("If the proc has lambda semantics. See class docs for an explanation about lambdas." or something like that.)
#1 [ruby-core:86164] Updated by shevegen (Robert A. Heiler) 6 months ago
If my class documentation would be accepted,
You added a lot more examples too if I understand the patch
correctly, so I guess it is better than the old status quo.
The old status quo did not have ... a lot of examples, which
is not good. Examples help a LOT. They are often easier to
understand than any wall of text - if they work that is. :)
And there was also some more documentation added about Symbols
versus Strings in ruby by ... (I forgot the name, i am so
sorry) some ruby hacker. So I think it is quite likely that
the patch will be added.
The only remark I have to make is that I think the old intro is
a bit better.
"Proc objects are blocks of code that have been bound to
a set of local variables."
"Proc object is an incapsulation of a block of code, that can be
stored in local variables, passed to methods and other procs and
Actually I think I just noticed a typo in your patch. :)
"+Proc+ object is an incapsulation of a block of code, that can
be stored in local variables, passed to methods and other procs
The part "and called" seems a bit odd. I assume you refer to
"called in another proc"?
Anyway. The above are mostly just details; it's not as if the
old documentation is perfect either. ;)
Some other changes I'd suggest would be e. g.:
"You can tell lambda from regular proc by #lambda? instance method."
"A lambda can be distinguished from a regular proc object by the #lambda? instance method. Example:"
And a single-line example.
Anyway, I agree with your statements above, so my comment should be
seen as suggestions to +1 to your patch. In general the ruby docs
are an area where a lot of things can be made better, so it's great
that people such as you help improve these parts of ruby.