Feature #14347: Explain How Symbols Differ From Strings in Symbol's Rdoc

• Status: Closed
• Assignee: -
• Target version: -

[jeremyevans0 (Jeremy Evans)]

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.

[dsferreira (Daniel Ferreira)]

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.

[duerst (Martin Dürst)]

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.

[jeremyevans0 (Jeremy Evans)]

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.

[jeremyevans0 (Jeremy Evans)]

• File 0001-Describe-difference-between-Symbol-and-String-classe.patch 0001-Describe-difference-between-Symbol-and-String-classe.patch added

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.

[shevegen (Robert A. Heiler)]

Yay for better documentation. \o/

[hsbt (Hiroshi SHIBATA)]

• Status changed from Open to Assigned
• Assignee set to 13939

• Status changed from Assigned to Closed

Applied in changeset git|2a5c3a4d0f693ad0fe7b76dd99155e57149d2cac.

---

Update documentation for String and Symbol to discuss differences

Implements [Feature #14347]