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.)
Updated by shevegen (Robert A. Heiler) 10 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.
Updated by zverok (Victor Shepelev) about 1 month ago
- Backport deleted (
2.3: UNKNOWN, 2.4: UNKNOWN, 2.5: UNKNOWN)
- Tracker changed from Bug to Misc
Added by zverok (Victor Shepelev) 9 months ago.
Updated by hsbt (Hiroshi SHIBATA) 4 months ago
Sorry, is it possible to have this merged before 2.6 release? What can I do for it?..