Improve docs of sets regarding mutability

[sorawee]

(Originally from https://stackoverflow.com/questions/55508775/why-does-set-union-and-friends-not-take-mutable-sets-as-arguments/55511479)

While the documentation does state that immutable sets implement set-union and mutable sets implement set-union!, this is written as a prose at the beginning of the section, so it's really easy to miss.

Would it be better to add in the documentation that st0 must satisfy (and/c generic-set? set-mutable?) for set-union! and (and/c generic-set? (not/c set-mutable?)) for set-union?

Relatedly, the documentation of set-implements? is misleading. In particular, the documentation shows without explanation that:

> (set-implements? (mutable-seteq 1 2 3) 'set-add)
#t

and yet:

> (set-add (mutable-seteq 1 2 3) 4)
; set-add:
; expected: (not/c set-mutable?)
; given mutable set: (mutable-seteq 1 2 3)
; argument position: 1st
; [,bt for context]

(I'm not arguing here that set-implements? is wrong, but the explanation should explain why the above happens).

[sorawee]

And now I have another issue similar to this: should set-copy work on immutable set?

Currently, it works:

> (set-copy (set 1 2 3))
(mutable-set 1 2 3)

However, the docs state:

Supported for any st that supports set->stream and implements set-copy-clear and set-add!.

There are many ways to interpret this statement.

1. set-copy should not work on set, because (set-add! (set 1 2 3) 4) results in an error.
2. set-copy should work on set, because (set-implements? (set 1 2 3) 'set-add!) is #t
3. set-copy might or might not work on set. "Supported for any st that supports" simply gives a lower bound guarantee, but it might work on other things too.

Which interpretation is intended to be used here?

Note that interpretation (2) is problematic, because it causes another violation. Consider the docs of set-clear!

Supported for any st that implements set-remove! and either supports set->stream or implements set-first and either set-count or set-empty?.

If we follow interpretation (2), then the fact that (set-implements? (set 1 2 3) 'set-remove!) returns #t implies that set-clear! should work on (set 1 2 3). However, that's not the case:

> (set-clear! (set 1 2 3))
set-clear!:
expected: (or/c set-mutable? set-weak?)
given immutable set: (set 1 2 3)