[ruby-core:84797] [Ruby trunk Feature#14347] Explain How Symbols Differ From Strings in Symbol's Rdoc

Issue #14347 has been updated by 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.

----------------------------------------
Feature #14347: Explain How Symbols Differ From Strings in Symbol's Rdoc
https://bugs.ruby-lang.org/issues/14347#change-69511

* Author: jeremyevans0 (Jeremy Evans)
* Status: Open
* Priority: Normal
* Assignee: 
* Target version: 
----------------------------------------
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--------------------------------
0001-Add-more-documentation-for-Symbol-class.patch (1.85 KB)


-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:[e-mail]?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>