Update documentation according to Effective Dart documentation guide

[osa1]

Effective Dart documentation section:
https://dart.dev/guides/language/effective-dart/documentation

This addresses reviews in cl/449413572 about the documentation in this library.

Summary of changes:

• Use noun phrases in getters, fields

• Replace [:...:] syntax with ``

• Use [...] syntax for in-scope identifiers in comments and documentation

• Use "create" instead of "return" for methods that create a new instance
  (rather than returning an existing one)

• Give a single sentence summary in API docs, move the rest to new paragraph(s)

• When documentation exception behavior, start the sentence with "Throws" in a
  new paragraph. Similarly when documenting return values do the same, starting
  with "Returns".

• Some rewording

• Use ArgumentError.value constructor in some cases (instead of
  ArgumentError)

Note that I did not review every line of comment/doc in the library to update
them according to the Effective Dart guidelines. This only addresses reviews
that came up in cl/449413572.

---

@lrhn Could you review please? (GitHub doesn't let me add you as a reviewer)

[sigurdm]

Very nice

LGTM

[lrhn]

Very nice, few nits.