[Chapel Merge] Update user-defined hash documentation

Branch: refs/heads/main
Revision: 75f11ba
Author: bradcray
Link: Update user-defined hash documentation by bradcray · Pull Request #19266 · chapel-lang/chapel · GitHub
Log Message:

Merge pull request #19266 from bradcray/userhash-doc-improvements

Update user-defined hash documentation

[reviewed by @mppf and @bmcdonald3 ]

This is a follow-on to #19243 to document when the compiler
will or will not provide a hash function for a user record. While
here, I also attempted to improve the existing documentation by:

  • making the spec example for a user-defined hash testable and
    complete, fixing some typos
  • providing a bit more context in the primer and removing the note
    about built-in types (since the primer is about special methods
    on classes and records and doesn't need to be as complete as
    the spec)
  • word-smithing
  • adding return types to the documentation examples of hash()

While here, I found myself questioning whether "returning int
or uint" was what we wanted to commit to, combined with
slight discomfort with the fact that the high bit is ignored in our
implementation without us saying so, so filed
What requirements do we want on the user-defined hash() return type / value? · Issue #19285 · chapel-lang/chapel · GitHub to capture
this concern.

Modified Files:
M doc/rst/language/spec/records.rst

M test/release/examples/primers/specialMethods.chpl

Compare: https://github.com/chapel-lang/chapel/compare/275f4fe65997...75f11baac824