From: shevegen@... Date: 2018-03-16T23:18:22+00:00 Subject: [ruby-core:86164] [Ruby trunk Misc#14610] Enhance Proc docs Issue #14610 has been updated by shevegen (Robert A. Heiler). Agreed. > 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. 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. E. g.: "Proc objects are blocks of code that have been bound to a set of local variables." versus "Proc object is an incapsulation of a block of code, that can be stored in local variables, passed to methods and other procs and called." 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 and called." 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." towards "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. ---------------------------------------- Misc #14610: Enhance Proc docs https://bugs.ruby-lang.org/issues/14610#change-71047 * Author: zverok (Victor Shepelev) * Status: Open * Priority: Normal * Assignee: ---------------------------------------- What caught me recently while mentoring students: there is almost no "canonical" explanation about procs in [Ruby's core docs](https://docs.ruby-lang.org/en/trunk/): 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. Things added: 1. More friendly and detailed explanation of the whole concept. 2. Different methods of creating lambda and non-lambda procs. 3. Lambda semantics. 4. 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.) ---Files-------------------------------- proc_docs.patch (6.41 KB) -- https://bugs.ruby-lang.org/ Unsubscribe: