Project

General

Profile

Actions

Feature #14347

closed

Explain How Symbols Differ From Strings in Symbol's Rdoc

Added by jeremyevans0 (Jeremy Evans) about 6 years ago. Updated over 2 years ago.

Status:
Closed
Assignee:
-
Target version:
-
[ruby-core:84794]

Description

This adds more detail to Symbol's RDoc, explaining how symbols differ from strings, and giving examples showing how ruby returns symbols for internal identifiers.


Files

Updated by dsferreira (Daniel Ferreira) about 6 years ago

Thanks Jeremy for this patch.

Could we add to the documentation the definition of identifier in ruby land?

Examples of good usage of symbols would be helpful as well.

This piece could also be extended for the hash in order to specifically document when to use symbols as keys or not explaining why we have two hash notations and when to use one or another.

Method arguments is also an area where symbols have a say.

All of this has a certain level of complexity that clear documentation helps to simplify.

Updated by duerst (Martin Dürst) about 6 years ago

jeremyevans0 (Jeremy Evans) wrote:

This adds more detail to Symbol's RDoc, explaining how symbols differ from strings, and giving examples showing how ruby returns symbols for internal identifiers.

Thanks, great idea. Just a small point: There should be at least a pointer, or some parallel explanation, in the documentation on String.

Updated by jeremyevans0 (Jeremy Evans) about 6 years ago

dsferreira (Daniel Ferreira) wrote:

Thanks Jeremy for this patch.

Could we add to the documentation the definition of identifier in ruby land?

I don't think there is ruby-specific context here, the standard computing definition applies ("name that identifies either a unique object or a unique class of objects"). I don't think it makes sense to explicitly define common terms.

Examples of good usage of symbols would be helpful as well.

The documentation states that symbols should be used for identifiers, and strings for text/data, so anytime you are using an identifier, a symbol is probably the proper object to use.

This piece could also be extended for the hash in order to specifically document when to use symbols as keys or not explaining why we have two hash notations and when to use one or another.

I'm not sure it makes sense to document hash syntax in the symbol class Rdoc. As to when to use symbols as keys, as above, if the key represents an identifier, a symbol is appropriate, otherwise probably not. I don't think Ruby's documentation is or should be prescriptive in terms of which hash syntax to use for symbol keys.

Method arguments is also an area where symbols have a say.

Method arguments are definitely identifiers, but by themselves are not symbols, in the same sense that a block is not a Proc. Are you referring to the return value of Method#parameters, which does contain symbols? That could be documented hereh, but is a little more complex and I'm not sure it adds much over the existing examples.

All of this has a certain level of complexity that clear documentation helps to simplify.

I'm not opposed to adding more documentation to the Symbol class Rdoc beyond what my patch adds, but there's definitely a cost/benefit consideration. More documentation is not necessarily better unless it adds insight not covered or implied by existing documentation.

Updated by jeremyevans0 (Jeremy Evans) about 6 years ago

duerst (Martin Dürst) wrote:

Thanks, great idea. Just a small point: There should be at least a pointer, or some parallel explanation, in the documentation on String.

I agree. Attached is a new patch that modifies the Rdoc for both String and Symbol.

Updated by shevegen (Robert A. Heiler) about 6 years ago

Yay for better documentation. \o/

Updated by hsbt (Hiroshi SHIBATA) over 5 years ago

  • Status changed from Open to Assigned
  • Assignee set to 13939
Actions #7

Updated by jeremyevans (Jeremy Evans) over 2 years ago

  • Status changed from Assigned to Closed

Applied in changeset git|2a5c3a4d0f693ad0fe7b76dd99155e57149d2cac.


Update documentation for String and Symbol to discuss differences

Implements [Feature #14347]

Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0Like0Like0