Better enum symbol casting documentation

[nobodywasishere]

Closes #705

[netlify]

✅ Deploy Preview for crystal-book ready!

Name	Link
🔨 Latest commit	4c6e9fc
🔍 Latest deploy log	https://app.netlify.com/sites/crystal-book/deploys/64dabaa7aef31c00087b5356
😎 Deploy Preview	https://deploy-preview-706--crystal-book.netlify.app/syntax_and_semantics/enum
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[Andriamanitra]

I think we should keep the old "Usage" section and add a new section for the symbol-enum autocasting. With the removal of the old example it is no longer clear how to use enums with a case statement. Especially this part that got removed provided helpful information:

However, if the programmer makes a typo, say :reed, the error will only be caught at runtime, while attempting to use Color::Reed will result in a compile-time error.

The recommended thing to do is to use enums whenever possible, only use symbols for the internal implementation of an API, and avoid symbols for public APIs. But you are free to do what you want.

[nobodywasishere]

I could add an example like:

case color
when Color::Red
  # red color
else
  # unknown color
end

But I think that should be an additional example, not included in the def paint code example for clarity. I did also add a link to how to use enums with case statements as defined on the case page, which provides a different example.

I don't think the sections you quoted relate to how to use a case statement, but to the benefits of using enums over symbols. Maybe it could fit but honestly don't know if it does tonally. Maybe it could be something like:

If a symbol parameter is being used to indicate flags or a set of options, it is recommended to use an enum instead. If the wrong symbol argument is used, enum symbol casting provides a compile-time error letting you know there's a problem. This is in contrast to using a using a symbol parameter which may not catch an error at all without manual value checking or guard statements, leading to issues downstream.

[straight-shoota]

I think it's fine like this. The paragraph mentioned in #706 (comment) is not very relevant for the enum page.
It talks about the shortcomings of symbol. So it should probably better be placed on the symbol page.