output module documentation reviewed

Author: rizsotto

bear/src/output/formats.rs

@@ -1,29 +1,46 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-//! This module is responsible for declaring the file formats this project
-//! is using. The following formats are declared:
+//! This module declares the file formats used by this project.
+//! The following formats are declared:
 //!
-//! - The JSON compilation database format. Declared by the Clang project.
-//! - The semantic database format. (Internal format of this project.)
-//! - The execution event database format. (Internal format of this project.)
+//! - The JSON compilation database format, as declared by the Clang project.
+//! - The semantic database format (internal format of this project).
+//! - The execution event database format (internal format of this project.)
 
 use super::json;
 use crate::{intercept, semantic, semantic::clang};
 use serde_json::de::IoRead;
 use serde_json::StreamDeserializer;
 use thiserror::Error;
 
-/// The trait represents a file format that can be written to and read from.
+/// Represents errors that can occur while working with file formats.
+#[derive(Debug, Error)]
+pub enum SerializationError {
+    #[error("Generic IO error: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("Format syntax error: {0}")]
+    Syntax(#[from] serde_json::Error),
+    #[error("Format semantic error: {0}")]
+    Semantic(#[from] clang::EntryError),
+}
+
+/// A trait representing a file format that can be written to and read from.
 ///
-/// The file format in this project is usually a sequence of values. This trait
-/// provides a type-independent abstraction over the file format.
+/// File formats in this project are usually sequences of values. This trait
+/// provides a type-independent abstraction over file formats.
 pub trait SerializationFormat<T> {
-    fn write(_: impl std::io::Write, _: impl Iterator<Item = T>) -> Result<(), SerializationError>;
+    /// Writes an iterator of items to the specified writer.
+    fn write(
+        writer: impl std::io::Write,
+        items: impl Iterator<Item = T>,
+    ) -> Result<(), SerializationError>;
 
-    fn read(_: impl std::io::Read) -> impl Iterator<Item = Result<T, SerializationError>>;
+    /// Reads items from the specified reader, returning an iterator of results.
+    fn read(reader: impl std::io::Read) -> impl Iterator<Item = Result<T, SerializationError>>;
 
-    /// Reads the entries from the file and ignores any errors.
-    /// This is not always feasible, when the file format is strict.
+    /// Reads entries from the file and ignores any errors.
+    ///
+    /// This is not always feasible when the file format is strict.
     fn read_and_ignore(
         reader: impl std::io::Read,
         message_writer: impl Fn(&str),
@@ -38,17 +55,6 @@ pub trait SerializationFormat<T> {
     }
 }
 
-/// Represents errors that can occur while working with file formats.
-#[derive(Debug, Error)]
-pub enum SerializationError {
-    #[error("Generic IO error: {0}")]
-    Io(#[from] std::io::Error),
-    #[error("Format syntax error: {0}")]
-    Syntax(#[from] serde_json::Error),
-    #[error("Format semantic error: {0}")]
-    Semantic(#[from] clang::EntryError),
-}
-
 /// The type represents a JSON compilation database format.
 ///
 /// The format is a JSON array format, which is a sequence of JSON objects
@@ -102,9 +108,9 @@ pub struct JsonSemanticDatabase;
 impl SerializationFormat<semantic::Command> for JsonSemanticDatabase {
     fn write(
         writer: impl std::io::Write,
-        entries: impl Iterator<Item = semantic::Command>,
+        commands: impl Iterator<Item = semantic::Command>,
     ) -> Result<(), SerializationError> {
-        json::serialize_seq(writer, entries).map_err(SerializationError::Syntax)
+        json::serialize_seq(writer, commands).map_err(SerializationError::Syntax)
     }
     fn read(
         _: impl std::io::Read,

bear/src/output/json.rs

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-//! The module contains functions to serialize and deserialize JSON arrays.
+//! This module contains functions to serialize and deserialize JSON arrays.
 //!
 //! The main objective is to provide a way to serialize and deserialize
 //! entries from an iterator into a JSON array and vice versa. Iterators
-//! allows us to process large datasets without loading everything into
+//! allow us to process large datasets without loading everything into
 //! memory at once.
 //!
-//! The format these methods are producing is a JSON array of objects.
+//! The format these methods produce is a JSON array of objects.
 //! It's *not* JSON lines format, which is a sequence of JSON objects
 //! separated by newlines.
 

bear/src/output/mod.rs

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-//! This module is responsible for writing the output of the semantic analysis.
+//! This module is responsible for writing the output of semantic analysis.
 //!
 //! The output can be in different formats, such as JSON compilation databases
 //! or semantic analysis results in JSON format. The module provides functionality
 //! to write these outputs to files, handle duplicates, and format the output
 //! as needed.
 //!
-//! The `OutputWriter` enum represents the main entry point for writing the output.
-//! The input of the `OutputWriter` is a stream of `semantic::CompilerCall` instances.
+//! The `OutputWriter` enum represents the main entry point for writing output.
+//! The input to the `OutputWriter` is a stream of `semantic::Command` instances.
 
 mod formats;
 mod json;
@@ -24,6 +24,11 @@ use writers::{
 // Re-export types for convenience.
 pub use formats::{ExecutionEventDatabase, SerializationError, SerializationFormat};
 
+/// A stack of output writers for Clang compilation databases.
+type ClangWriterStack = ConverterClangOutputWriter<
+    AppendClangOutputWriter<AtomicClangOutputWriter<UniqueOutputWriter<ClangOutputWriter>>>,
+>;
+
 /// Represents the output writer, which can handle different types of outputs.
 ///
 /// This enum provides two variants:
@@ -33,11 +38,7 @@ pub use formats::{ExecutionEventDatabase, SerializationError, SerializationForma
 /// The variants are selected at runtime based on the configuration provided.
 pub enum OutputWriter {
     #[allow(private_interfaces)]
-    Clang(
-        ConverterClangOutputWriter<
-            AppendClangOutputWriter<AtomicClangOutputWriter<UniqueOutputWriter<ClangOutputWriter>>>,
-        >,
-    ),
+    Clang(ClangWriterStack),
     #[allow(private_interfaces)]
     Semantic(SemanticOutputWriter),
 }
@@ -75,6 +76,13 @@ impl TryFrom<(&args::BuildSemantic, &config::Output)> for OutputWriter {
 }
 
 impl OutputWriter {
+    /// Writes semantic commands using the configured output writer.
+    ///
+    /// # Arguments
+    /// * `semantics` - An iterator of semantic commands to write
+    ///
+    /// # Returns
+    /// `Ok(())` on success, or a `WriterError` if writing fails.
     pub fn write(
         self,
         semantics: impl Iterator<Item = semantic::Command>,

bear/src/output/writers.rs

@@ -8,18 +8,19 @@ use crate::semantic::clang::{DuplicateEntryFilter, Entry};
 use crate::{config, semantic};
 use std::{fs, io, path};
 
-/// The trait represents a writer for iterator type `T`.
+/// A trait representing a writer for iterator type `T`.
 ///
 /// This trait is implemented by types that can consume an iterator of type `T`
 /// and write its elements to some output. The writing process may succeed or fail,
 /// returning either `()` on success or an error.
 pub(super) trait IteratorWriter<T> {
     /// Writes the iterator as a sequence of elements.
-    /// It consumes the iterator and returns either a nothing or an error.
-    fn write(self, _: impl Iterator<Item = T>) -> Result<(), WriterError>;
+    ///
+    /// Consumes the iterator and returns either nothing on success or an error.
+    fn write(self, items: impl Iterator<Item = T>) -> Result<(), WriterError>;
 }
 
-/// This writer is used to write the semantic analysis results to a file.
+/// The type represents a writer for semantic analysis results to a file.
 ///
 /// # Note
 /// The output format is not stable and may change in future versions.
@@ -51,7 +52,7 @@ impl IteratorWriter<semantic::Command> for SemanticOutputWriter {
     }
 }
 
-/// Formats `semantic::CompilerCall` instances into `Entry` objects.
+/// The type represents a converter that formats `semantic::Command` instances into `Entry` objects.
 pub(super) struct ConverterClangOutputWriter<T: IteratorWriter<Entry>> {
     format: config::EntryFormat,
     writer: T,
@@ -73,7 +74,7 @@ impl<T: IteratorWriter<Entry>> IteratorWriter<semantic::Command> for ConverterCl
     }
 }
 
-/// Handles the logic for appending entries to an existing Clang output file.
+/// The type represents a writer that handles appending entries to an existing Clang output file.
 ///
 /// This writer supports reading existing entries from a compilation database file,
 /// combining them with new entries, and writing the result back to the file.
@@ -129,7 +130,7 @@ impl<T: IteratorWriter<Entry>> IteratorWriter<Entry> for AppendClangOutputWriter
     }
 }
 
-/// Responsible for writing a JSON compilation database file atomically.
+/// The type represents a writer that writes JSON compilation database files atomically.
 ///
 /// The file is first written to a temporary file and then renamed to the final file name.
 /// This ensures that the output file is not left in an inconsistent state in case of errors.
@@ -160,7 +161,7 @@ impl<T: IteratorWriter<Entry>> IteratorWriter<Entry> for AtomicClangOutputWriter
     }
 }
 
-/// Responsible for writing a JSON compilation database file from the given entries.
+/// The type represents a writer that writes JSON compilation database files from given entries.
 ///
 /// # Features
 /// - Filters duplicates based on the provided configuration.
@@ -190,7 +191,7 @@ impl<T: IteratorWriter<Entry>> IteratorWriter<Entry> for UniqueOutputWriter<T> {
     }
 }
 
-/// Responsible for writing a JSON compilation database file from the given entries.
+/// The type represents a writer that writes JSON compilation database files from given entries.
 ///
 /// # Features
 /// - Writes the entries to a file.