should and must are the same semantically. But it’s not about better documentation, it’s basically just down to personal stylistic preference (I prefer must for example).
can is a little different. You can’t (nomen omen) use it directly as a matcher, it’s only available in a test descriptor. Quote from FlatSpec:
Note: you can use must or can as well as should in a FlatSpec. For
example, instead of it should “pop…, you could write it must “pop…
or it can “pop….
(the same applies for WordSpec and the two corresponding fixture classes)
Note that for a short time (in ScalaTest 2.0.x I think), the use of must was deprecated, however, in 2.1.0, the decision has been reverted:
Resurrected MustMatchers in package org.scalatest. Changed deprecation
warning for org.scalatest.matchers.MustMatchers to suggest using
org.scalatest.MustMatchers instead of org.scalatest.Matchers, which
was the suggestion in 2.0. Apologies to must users who migrated to
should already when upgrading to 2.0.