Clarify example in opaque type documentation

[panacekcz]

The last example at https://dotty.epfl.ch/docs/reference/other-new-features/opaques.html causes repeated confusion, showing in #7259, #8423 and https://contributors.scala-lang.org/t/proposal-for-opaque-type-aliases/2947/90 .

This PR attempts to remove all possible sources of confusion and unambiguously describe my understanding of the example.

[dottybot]

Hello, and thank you for opening this PR! 🎉

All contributors have signed the CLA, thank you! ❤️

Have an awesome day! ☀️

[DaniRey]

Great catch @panacekcz

Currently this example is a bit of a Dotty Puzzler (http://www.javapuzzlers.com/), which is maybe not the best way to introduce a concept.

I would suggest to rewrite the code as follows. and combine this with the additional description you suggested.

object Access {

  opaque type Permissions = Int
  opaque type PermissionChoice = Int
  opaque type Permission <: Permissions & PermissionChoice = Int

  def (x: Permissions) and (y: Permissions): Permissions = x | y
  def (x: PermissionChoice) or (y: PermissionChoice): PermissionChoice = x | y
  def (x: Permissions).is(y: Permissions) = (x & y) == y
  def (x: Permissions).isOneOf(y: PermissionChoice) = (x & y) != 0

  val NoPermission: Permission = 0
  val ReadOnly: Permission = 1
  val WriteOnly: Permission = 2
}

object User {
  import Access._

  case class Item(rights: Permissions)

  //if this would be in Access it would have to use `|` instead of `and`,
  //because Permissions is an Int within Access
  val ReadWrite: Permissions = ReadOnly and WriteOnly

  val ReadOrWrite: PermissionChoice = ReadOnly or WriteOnly

  val x = Item(ReadOnly)  // OK, since Permission <: Permissions

  assert( x.rights.is(ReadWrite) == false )
  assert( x.rights.isOneOf(ReadOrWrite) == true )
}

I moved ReadWrite and ReadOrWriteto the User object and replaced | and & with and and or to better disambiguate between the extension method and the operators on Int

[odersky]

Yes, much better this way.

[odersky]

Thanks for making the improvements!