lib: add short method summary to its documentation

lib/src/conflicts.rs

@@ -367,10 +367,12 @@ pub fn materialized_diff_stream<'a>(
         .buffered((store.concurrency() / 2).max(1))
 }
 
-/// Parses conflict markers from a slice. Returns None if there were no valid
-/// conflict markers. The caller has to provide the expected number of merge
-/// sides (adds). Conflict markers that are otherwise valid will be considered
-/// invalid if they don't have the expected arity.
+/// Parse conflict markers from a slice
+///
+/// Returns `None` if there were no valid conflict markers. The caller
+/// has to provide the expected number of merge sides (adds). Conflict
+/// markers that are otherwise valid will be considered invalid if
+/// they don't have the expected arity.
 // TODO: "parse" is not usually the opposite of "materialize", so maybe we
 // should rename them to "serialize" and "deserialize"?
 pub fn parse_conflict(input: &[u8], num_sides: usize) -> Option<Vec<Merge<BString>>> {

lib/src/diff.rs

@@ -672,11 +672,13 @@ impl<'diff, 'input> Iterator for DiffHunkIterator<'diff, 'input> {
     }
 }
 
-/// Diffs slices of bytes. The returned diff hunks may be any length (may
-/// span many lines or may be only part of a line). This currently uses
-/// Histogram diff (or maybe something similar; I'm not sure I understood the
-/// algorithm correctly). It first diffs lines in the input and then refines
-/// the changed ranges at the word level.
+/// Diff slices of bytes
+///
+/// The returned diff hunks may be any length (may span many lines or
+/// may be only part of a line). This currently uses Histogram diff
+/// (or maybe something similar; I'm not sure I understood the
+/// algorithm correctly). It first diffs lines in the input and then
+/// refines the changed ranges at the word level.
 pub fn diff<'a, T: AsRef<[u8]> + ?Sized + 'a>(
     inputs: impl IntoIterator<Item = &'a T>,
 ) -> Vec<DiffHunk<'a>> {

lib/src/fsmonitor.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Filesystem monitor tool interface
+//!
 //! Interfaces with a filesystem monitor tool to efficiently query for
 //! filesystem updates, without having to crawl the entire working copy. This is
 //! particularly useful for large working copies, or for working copies for

lib/src/merge.rs

@@ -519,10 +519,12 @@ impl<T: ContentHash> ContentHash for Merge<T> {
 /// Borrowed `MergedTreeValue`.
 pub type MergedTreeVal<'a> = Merge<Option<&'a TreeValue>>;
 
-/// The value at a given path in a commit. It depends on the context whether it
-/// can be absent (`Merge::is_absent()`). For example, when getting the value at
-/// a specific path, it may be, but when iterating over entries in a tree, it
-/// shouldn't be.
+/// Value at a given path in a commit
+///
+/// It depends on the context whether it can be absent
+/// (`Merge::is_absent()`). For example, when getting the value at a
+/// specific path, it may be, but when iterating over entries in a
+/// tree, it shouldn't be.
 pub type MergedTreeValue = Merge<Option<TreeValue>>;
 
 impl MergedTreeValue {

lib/src/merged_tree.rs

@@ -1101,7 +1101,9 @@ impl Stream for TreeDiffStreamImpl<'_> {
     }
 }
 
-/// Helps with writing trees with conflicts. You start by creating an instance
+/// Helper for writing trees with conflicts
+///
+/// You start by creating an instance
 /// of this type with one or more base trees. You then add overrides on top. The
 /// overrides may be conflicts. Then you can write the result as a legacy tree
 /// (allowing path-level conflicts) or as multiple conflict-free trees.

lib/src/rewrite.rs

@@ -462,6 +462,9 @@ pub struct MoveCommitsStats {
     pub num_skipped_rebases: u32,
 }
 
+/// Rebase and move `target_commits` in graph based on new parent and child
+/// nodes
+///
 /// Moves `target_commits` from their current location to a new location in the
 /// graph, given by the set of `new_parent_ids` and `new_children`.
 /// The roots of `target_commits` are rebased onto the new parents, while the

lib/src/stacked_table.rs

@@ -12,11 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! A persistent table of fixed-size keys to variable-size values. The keys are
-//! stored in sorted order, with each key followed by an integer offset into the
-//! list of values. The values are concatenated after the keys. A file may have
-//! a parent file, and the parent may have its own parent, and so on. The child
-//! file then represents the union of the entries.
+//! A oersistent table of fixed-size keys to variable-size values
+//!
+//! The keys are stored in sorted order, with each key followed by an
+//! integer offset into the list of values. The values are
+//! concatenated after the keys. A file may have a parent file, and
+//! the parent may have its own parent, and so on. The child file then
+//! represents the union of the entries.
 
 #![allow(missing_docs)]
 

lib/src/transaction.rs

@@ -164,6 +164,8 @@ pub fn create_op_metadata(
     }
 }
 
+/// Manage unpublished operations in the store
+///
 /// An Operation which has been written to the operation store but not
 /// published. The repo can be loaded at an unpublished Operation, but the
 /// Operation will not be visible in the op log if the repo is loaded at head.

lib/src/workspace.rs

@@ -93,6 +93,8 @@ pub enum WorkspaceLoadError {
     Path(#[from] PathError),
 }
 
+/// Combination of a repo and a working copy
+///
 /// 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>