Project

General

Profile

Feature #14347

Explain How Symbols Differ From Strings in Symbol's Rdoc

Added by jeremyevans0 (Jeremy Evans) 6 months ago. Updated 6 months ago.

Status:
Open
Priority:
Normal
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.

History

#1 [ruby-core:84795] Updated by dsferreira (Daniel Ferreira) 6 months 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.

#2 [ruby-core:84796] Updated by duerst (Martin Dürst) 6 months 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.

#3 [ruby-core:84797] Updated by jeremyevans0 (Jeremy Evans) 6 months 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.

#4 [ruby-core:84799] Updated by jeremyevans0 (Jeremy Evans) 6 months 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.

#5 [ruby-core:84804] Updated by shevegen (Robert A. Heiler) 6 months ago

Yay for better documentation. \o/

Also available in: Atom PDF