ocaml-yaml: lift yaml.mli to Bünzli quality, fix stale compare doc

Match the style nox-json's [json.mli] uses: inline submodule
declarations, with section-level prose covering broader contracts and
brief per-value docs. Three sections re-written:

- [module Sort]: explicit lowercase-name list, [or_kind] / [kinded]
semantics spelled out.
- [module Cursor]: peek/next contract precise (look-ahead, drained
past EOS), [skip_value] explicit about consuming exactly one
balanced subtree, [start_document] / [end_document] paired as
bracketing.
- Top-level decode/encode: explain the [string]-vs-[Error.t] error
variants, document [?flow]'s effect on style, surface the
[Invalid_utf8_encode] exception in [encode]'s contract,
[decode_stream] empty-stream behaviour.

Also fix the stale [compare] doc in the [Value] submodule — it still
claimed "[Stdlib.compare]" after the prior commit replaced the impl
with a structural compare. Now describes the sort-rank ordering and
points to {!Value.compare} for the full contract.