Remove weird Cell example from InvariantType docs (attempt #2)

[leejunseok]

Should fix #20147

This is my second PR in the history of ever (I botched my first one #21828). Any tips would be appreciated!

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @nikomatsakis (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see CONTRIBUTING.md for more information.

[steveklabnik]

@bors: r+ 310ada0

[nikomatsakis]

This is not strictly true. That is, all types must use unsafe code to achieve interior mutability. And if they do so, types should use an InvariantType marker (though this is likely to be replaced; see RFC rust-lang/rfcs#738). The only exception to that last rule is Cell, which has no marker because it is builtin to the compiler.

[nikomatsakis]

Let me put this another, hopefully clearer, way:

1. UnsafeCell and its wrapper Cell are the best ways to have interior mutability. If you use those, you do not need any markers.
2. Cell types are required if you are making some data that is truly interior to your struct (i.e., no pointer direction required to reach it) mutable. This is because the compiler has to know whether the interior of a struct is mutable for various safety checks relating to static data.
3. You may need a marker if you have a pointer like *mut T that gets transmuted or cast in your code to *mut U and that U is mutated when only reachable through a shared reference. In that case, you want a marker InvariantType<U>, because the fact that U will be mutated cannot be observed from the type definition alone -- the compiler sees *mut T, but doesn't know that it will eventually be transmuted to *mut U.

I guess it depends on how one defined "interior" mutability. The only legal way to have some data that is contained within your struct be mutable via a shared reference is to use UnsafeCell, in which case

[bors]

⌛ Testing commit 310ada0 with merge a08504b...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-32-nopt-t, auto-win-32-opt, auto-win-64-nopt-t, auto-win-64-opt