Add documentation comments for several types

These comments are intended to make it easier for new developers to get up to
speed with the project. This is just a starting point... there are other types
and functions that could benefit from documentation.

lib/src/backend.rs

@@ -72,13 +72,15 @@ impl Timestamp {
     }
 }
 
+/// Represents a [`Commit`] signature.
 #[derive(ContentHash, Debug, PartialEq, Eq, Clone)]
 pub struct Signature {
     pub name: String,
     pub email: String,
     pub timestamp: Timestamp,
 }
 
+/// Represents a cryptographically signed [`Commit`] signature.
 #[derive(ContentHash, Debug, PartialEq, Eq, Clone)]
 pub struct SecureSig {
     pub data: Vec<u8>,
@@ -331,6 +333,7 @@ pub fn make_root_commit(root_change_id: ChangeId, empty_tree_id: TreeId) -> Comm
     }
 }
 
+/// Defines the interface for commit backends.
 #[async_trait]
 pub trait Backend: Send + Sync + Debug {
     fn as_any(&self) -> &dyn Any;

lib/src/fsmonitor.rs

@@ -26,7 +26,7 @@ use std::str::FromStr;
 /// The recognized kinds of filesystem monitors.
 #[derive(Eq, PartialEq)]
 pub enum FsmonitorKind {
-    /// The Watchman filesystem monitor (https://facebook.github.io/watchman/).
+    /// The Watchman filesystem monitor (<https://facebook.github.io/watchman/>).
     Watchman,
 
     /// Only used in tests.

lib/src/object_id.rs

@@ -103,14 +103,19 @@ macro_rules! impl_id_type {
 
 pub(crate) use {id_type, impl_id_type};
 
+/// An identifier prefix (typically from a type implementing the [`ObjectId`]
+/// trait) with facilities for converting between bytes and a hex string.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct HexPrefix {
-    // For odd-length prefix, lower 4 bits of the last byte is padded with 0
+    // For odd-length prefixes, the lower 4 bits of the last byte are
+    // zero-filled (e.g. the prefix "abc" is stored in two bytes as "abc0").
     min_prefix_bytes: Vec<u8>,
     has_odd_byte: bool,
 }
 
 impl HexPrefix {
+    /// Returns a new `HexPrefix` or `None` if `prefix` cannot be decoded from
+    /// hex to bytes.
     pub fn new(prefix: &str) -> Option<HexPrefix> {
         let has_odd_byte = prefix.len() & 1 != 0;
         let min_prefix_bytes = if has_odd_byte {
@@ -160,6 +165,7 @@ impl HexPrefix {
         }
     }
 
+    /// Returns whether the stored prefix matches the prefix of `id`.
     pub fn matches<Q: ObjectId>(&self, id: &Q) -> bool {
         let id_bytes = id.as_bytes();
         let (maybe_odd, prefix) = self.split_odd_byte();
@@ -175,6 +181,7 @@ impl HexPrefix {
     }
 }
 
+/// The result of a prefix search.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum PrefixResolution<T> {
     NoMatch,

lib/src/workspace.rs

@@ -75,8 +75,10 @@ pub enum WorkspaceLoadError {
     Path(#[from] PathError),
 }
 
-/// Represents a workspace, i.e. what's typically the .jj/ directory and its
-/// parent.
+/// Represents the combination of a repo and working copy, i.e. what's typically
+/// the .jj/ directory and its parent. See
+/// <https://github.com/martinvonz/jj/blob/main/docs/working-copy.md#workspaces>
+/// for more information.
 pub struct Workspace {
     // Path to the workspace root (typically the parent of a .jj/ directory), which is where
     // working copy files live.