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);