From fa17944387e98cc46410162b7d020dcf5106cc48 Mon Sep 17 00:00:00 2001
From: Evan Mesterhazy <emesterhazy@google.com>
Date: Mon, 12 Feb 2024 16:01:11 -0500
Subject: [PATCH] Add documentation comments for operation, transaction, and
 view types

---
 cli/src/cli_util.rs    | 14 ++++++++++++--
 lib/src/operation.rs   |  2 ++
 lib/src/transaction.rs | 11 +++++++++++
 lib/src/view.rs        |  1 +
 4 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/cli/src/cli_util.rs b/cli/src/cli_util.rs
index dc5aa065e8..eea317ef77 100644
--- a/cli/src/cli_util.rs
+++ b/cli/src/cli_util.rs
@@ -359,8 +359,8 @@ impl ReadonlyUserRepo {
     }
 }
 
-// Provides utilities for writing a command that works on a workspace (like most
-// commands do).
+/// Provides utilities for writing a command that works on a [`Workspace`]
+/// (which most commands do).
 pub struct WorkspaceCommandHelper {
     cwd: PathBuf,
     string_args: Vec<String>,
@@ -1286,6 +1286,12 @@ Then run `jj squash` to move the resolution into the conflicted commit."#,
     }
 }
 
+/// A [`Transaction`] tied to a particular workspace.
+/// `WorkspaceCommandTransaction`s are created with
+/// [`WorkspaceCommandHelper::start_transaction`] and committed with
+/// [`WorkspaceCommandTransaction::finish`]. The inner `Transaction` can also be
+/// extracted using [`WorkspaceCommandTransaction::into_inner`] in situations
+/// where finer-grained control over the `Transaction` is necessary.
 #[must_use]
 pub struct WorkspaceCommandTransaction<'a> {
     helper: &'a mut WorkspaceCommandHelper,
@@ -1351,6 +1357,10 @@ impl WorkspaceCommandTransaction<'_> {
         self.helper.finish_transaction(ui, self.tx, description)
     }
 
+    /// Returns the wrapped [`Transaction`] for circumstances where
+    /// finer-grained control is needed. The caller becomes responsible for
+    /// finishing the `Transaction`, including rebasing descendants and updating
+    /// the working copy, if applicable.
     pub fn into_inner(self) -> Transaction {
         self.tx
     }
diff --git a/lib/src/operation.rs b/lib/src/operation.rs
index f8d0115a9d..3a007485bb 100644
--- a/lib/src/operation.rs
+++ b/lib/src/operation.rs
@@ -23,6 +23,8 @@ use crate::op_store;
 use crate::op_store::{OpStore, OpStoreResult, OperationId, OperationMetadata, ViewId};
 use crate::view::View;
 
+/// A wrapper around [`op_store::Operation`] that defines additional methods and
+/// stores a pointer to the `OpStore` the operation belongs to.
 #[derive(Clone)]
 pub struct Operation {
     op_store: Arc<dyn OpStore>,
diff --git a/lib/src/transaction.rs b/lib/src/transaction.rs
index 9145da348b..7fa8d1b2b7 100644
--- a/lib/src/transaction.rs
+++ b/lib/src/transaction.rs
@@ -27,6 +27,17 @@ use crate::settings::UserSettings;
 use crate::view::View;
 use crate::{dag_walk, op_store};
 
+/// An in-memory representation of a repo and any changes being made to it.
+///
+/// Within the scope of a transaction, changes to the repository are made
+/// in-memory to `mut_repo` and published to the repo backend when
+/// [`Transaction::commit`] is called. When a transaction is committed, it
+/// becomes atomically visible as an Operation in the op log that represents the
+/// transaction itself, and as a View that represents the state of the repo
+/// after the transaction. This is similar to how a Commit represents a change
+/// to the contents of the repository and a Tree represents the repository's
+/// contents after the change. See the documentation for [`op_store::Operation`]
+/// and [`op_store::View`] for more information.
 pub struct Transaction {
     mut_repo: MutableRepo,
     parent_ops: Vec<Operation>,
diff --git a/lib/src/view.rs b/lib/src/view.rs
index a11c2add97..4a1b3af1bb 100644
--- a/lib/src/view.rs
+++ b/lib/src/view.rs
@@ -24,6 +24,7 @@ use crate::refs::LocalAndRemoteRef;
 use crate::str_util::StringPattern;
 use crate::{op_store, refs};
 
+/// A wrapper around [`op_store::View`] that defines additional methods.
 #[derive(PartialEq, Eq, Debug, Clone)]
 pub struct View {
     data: op_store::View,