[ruby-core:86157] [Ruby trunk Misc#14610] Enhance Proc docs

[ruby-core:86157] [Ruby trunk Misc#14610] Enhance Proc docs

[zverok.offline]

Issue #14610 has been reported by zverok (Victor Shepelev).

----------------------------------------
Misc #14610: Enhance Proc docs
https://bugs.ruby-lang.org/issues/14610

* 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/

[ruby-core:86164] [Ruby trunk Misc#14610] Enhance Proc docs

[shevegen]

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/

[ruby-core:87109] [Ruby trunk Bug#14610] Enhance Proc docs

[naruse]

Issue #14610 has been updated by naruse (Yui NARUSE).

Tracker changed from Misc to Bug
Assignee set to docs
Backport set to 2.3: UNKNOWN, 2.4: UNKNOWN, 2.5: UNKNOWN

----------------------------------------
Bug #14610: Enhance Proc docs
https://bugs.ruby-lang.org/issues/14610#change-72088

* Author: zverok (Victor Shepelev)
* Status: Open
* Priority: Normal
* Assignee: docs
* Target version: 
* ruby -v: 
* Backport: 2.3: UNKNOWN, 2.4: UNKNOWN, 2.5: UNKNOWN
----------------------------------------
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/

[ruby-core:90426] [Ruby trunk Misc#14610] Enhance Proc docs

[zverok.offline]

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/

[ruby-core:90433] [Ruby trunk Misc#14610] Enhance Proc docs

[duerst]

Issue #14610 has been updated by duerst (Martin Dürst).

Assignee changed from docs to duerst (Martin Dürst)

I'll try to have a look at it later today or tomorrow.

----------------------------------------
Misc #14610: Enhance Proc docs
https://bugs.ruby-lang.org/issues/14610#change-75587

* Author: zverok (Victor Shepelev)
* Status: Assigned
* Priority: Normal
* Assignee: duerst (Martin Dürst)
----------------------------------------
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/