From 504bca9ee651cbc8d64a8e0f3cdfad0315478350 Mon Sep 17 00:00:00 2001 From: Alona Enraght-Moony Date: Tue, 14 May 2024 20:50:05 +0000 Subject: [PATCH] rustdoc-json-types: Document `Id` --- src/rustdoc-json-types/lib.rs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/rustdoc-json-types/lib.rs b/src/rustdoc-json-types/lib.rs index 164f88faa314a..a9882be930c6f 100644 --- a/src/rustdoc-json-types/lib.rs +++ b/src/rustdoc-json-types/lib.rs @@ -188,7 +188,19 @@ pub enum TypeBindingKind { Constraint(Vec), } -#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] +/// An opaque identifier for an item. +/// +/// It can be used to lookup in [Crate::index] or [Crate::paths] to resolve it +/// to an [Item]. +/// +/// Id's are only valid within a single JSON blob. They cannot be used to +/// resolve references between the JSON output's for different crates. +/// +/// Rustdoc makes no guarantees about the inner value of Id's. Applications +/// should treat them as opaque keys to lookup items, and avoid attempting +/// to parse them, or otherwise depend on any implementation details. +#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] +// FIXME(aDotInTheVoid): Consider making this non-public in rustdoc-types. pub struct Id(pub String); #[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]