Add documentation comments for operation, transaction, and view types

Author: emesterhazy

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
     }

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>,

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>,

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,