From: zverok.offline@... Date: 2018-12-11T22:04:33+00:00 Subject: [ruby-core:90426] [Ruby trunk Misc#14610] Enhance Proc docs Issue #14610 has been updated by zverok (Victor Shepelev). Tracker changed from Bug to Misc Backport deleted (2.3: UNKNOWN, 2.4: UNKNOWN, 2.5: UNKNOWN) > 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?.. ---------------------------------------- Misc #14610: Enhance Proc docs https://bugs.ruby-lang.org/issues/14610#change-75579 * Author: zverok (Victor Shepelev) * Status: Assigned * Priority: Normal * Assignee: docs ---------------------------------------- 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: