elaborate the docs of FORMAT_VERSION

src/rustdoc-json-types/lib.rs

@@ -7,7 +7,11 @@ use rustc_hash::FxHashMap;
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
 
-/// rustdoc format-version.
+/// The version of JSON output that this crate represents.
+///
+/// This integer is incremented with every breaking change to the API,
+/// and is returned along with the JSON blob as [`Crate::format_version`].
+/// Consuming code should assert that this value matches the format version(s) that it supports.
 pub const FORMAT_VERSION: u32 = 32;
 
 /// The root of the emitted JSON blob.