From a28beb5b8ff08be4146b0442da660ebdeea8ac7c Mon Sep 17 00:00:00 2001
From: Evan Mesterhazy <emesterhazy@google.com>
Date: Mon, 12 Feb 2024 16:01:11 -0500
Subject: [PATCH] Allow id_type! to capture doc comments

This allows us to define documentation comments for types implemented using the
id_type! macro. Comments defined above the type inside the macro will be
captured and visible in generated docs.

Example:

```
id_type!(
    /// Stable identifier for a [`Commit`]. Unlike the `CommitId`, the `ChangeId`
    /// follows the commit and is not updated when the commit is rewritten.
    pub ChangeId
);
```

This commit also adds documentation for the `CommitId` and `ChangeId` types
defined using the `id_type!` macro.
---
 lib/src/backend.rs   | 12 ++++++++++--
 lib/src/object_id.rs | 19 ++++++++++++++++++-
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/lib/src/backend.rs b/lib/src/backend.rs
index 276de4ec25..d4fbf31dae 100644
--- a/lib/src/backend.rs
+++ b/lib/src/backend.rs
@@ -32,8 +32,16 @@ use crate::object_id::{id_type, ObjectId};
 use crate::repo_path::{RepoPath, RepoPathComponent, RepoPathComponentBuf};
 use crate::signing::SignResult;
 
-id_type!(pub CommitId);
-id_type!(pub ChangeId);
+id_type!(
+    /// Identifier for a [`Commit`] based on its content. When a commit is
+    /// rewritten, its `CommitId` changes.
+    pub CommitId
+);
+id_type!(
+    /// Stable identifier for a [`Commit`]. Unlike the `CommitId`, the `ChangeId`
+    /// follows the commit and is not updated when the commit is rewritten.
+    pub ChangeId
+);
 id_type!(pub TreeId);
 id_type!(pub FileId);
 id_type!(pub SymlinkId);
diff --git a/lib/src/object_id.rs b/lib/src/object_id.rs
index 89f6c9bb6d..a0b57e9ab4 100644
--- a/lib/src/object_id.rs
+++ b/lib/src/object_id.rs
@@ -21,8 +21,25 @@ pub trait ObjectId {
     fn hex(&self) -> String;
 }
 
+// Defines a new struct type with visibility `vis` and name `ident` containing
+// a single Vec<u8> used to store an identifier (typically the output of a hash
+// function) as bytes. Types defined using this macro automatically implement
+// the `ObjectId` and `ContentHash` traits.
+// Documentation comments written inside the macro definition and will be
+// captured and associated with the type defined by the macro.
+//
+// Example:
+// ```no_run
+// id_type!(
+//     /// My favorite id type.
+//     pub MyId
+// );
+// ```
 macro_rules! id_type {
-    ($vis:vis $name:ident) => {
+    (   $(#[$attr:meta])*
+        $vis:vis $name:ident
+    ) => {
+        $(#[$attr])*
         #[derive(ContentHash, PartialEq, Eq, PartialOrd, Ord, Clone, Hash)]
         $vis struct $name(Vec<u8>);
         $crate::object_id::impl_id_type!($name);