From acf1ba3f8f1492b961c9a6eb09eb93e882f5eb3f Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@liw.fi>
Date: Fri, 31 Dec 2021 09:00:21 +0200
Subject: docs: add documentation comments to crate

Also, make it an error for a public symbol to not be documented.

Sponsored-by: author
---
 src/chunk.rs | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

(limited to 'src/chunk.rs')

diff --git a/src/chunk.rs b/src/chunk.rs
index 266d1a7..15e3288 100644
--- a/src/chunk.rs
+++ b/src/chunk.rs
@@ -1,15 +1,18 @@
+//! Chunks of data.
+
 use crate::checksummer::Checksum;
 use crate::chunkid::ChunkId;
 use crate::chunkmeta::ChunkMeta;
 use serde::{Deserialize, Serialize};
 use std::default::Default;
 
-/// Store an arbitrary chunk of data.
-///
-/// The data is just arbitrary binary data.
+/// An arbitrary chunk of arbitrary binary data.
 ///
 /// A chunk also contains its associated metadata, except its
-/// identifier.
+/// identifier, so that it's easy to keep the data and metadata
+/// together. The identifier is used to find the chunk, and it's
+/// assigned by the server when the chunk is uploaded, so it's not
+/// stored in the chunk itself.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct DataChunk {
     data: Vec<u8>,
@@ -17,7 +20,7 @@ pub struct DataChunk {
 }
 
 impl DataChunk {
-    /// Construct a new chunk.
+    /// Create a new chunk.
     pub fn new(data: Vec<u8>, meta: ChunkMeta) -> Self {
         Self { data, meta }
     }
@@ -33,6 +36,13 @@ impl DataChunk {
     }
 }
 
+/// A chunk representing a backup generation.
+///
+/// A generation chunk lists all the data chunks for the SQLite file
+/// with the backup's metadata. It's different from a normal data
+/// chunk so that we can do things that make no sense to a data chunk.
+/// Generation chunks can be converted into or created from data
+/// chunks, for uploading to or downloading from the server.
 #[derive(Default, Debug, Serialize, Deserialize)]
 pub struct GenerationChunk {
     chunk_ids: Vec<ChunkId>,
@@ -41,39 +51,48 @@ pub struct GenerationChunk {
 /// All the errors that may be returned for `GenerationChunk` operations.
 #[derive(Debug, thiserror::Error)]
 pub enum GenerationChunkError {
+    /// Error converting text from UTF8.
     #[error(transparent)]
     Utf8Error(#[from] std::str::Utf8Error),
 
+    /// Error parsing JSON as chunk metadata.
     #[error("failed to parse JSON: {0}")]
     JsonParse(serde_json::Error),
 
+    /// Error generating JSON from chunk metadata.
     #[error("failed to serialize to JSON: {0}")]
     JsonGenerate(serde_json::Error),
 }
 
 impl GenerationChunk {
+    /// Create a new backup generation chunk from metadata chunk ids.
     pub fn new(chunk_ids: Vec<ChunkId>) -> Self {
         Self { chunk_ids }
     }
 
+    /// Create a new backup generation chunk from a data chunk.
     pub fn from_data_chunk(chunk: &DataChunk) -> Result<Self, GenerationChunkError> {
         let data = chunk.data();
         let data = std::str::from_utf8(data)?;
         serde_json::from_str(data).map_err(GenerationChunkError::JsonParse)
     }
 
+    /// Does the generation chunk contain any metadata chunks?
     pub fn is_empty(&self) -> bool {
         self.chunk_ids.is_empty()
     }
 
+    /// How many metadata chunks does generation chunk contain?
     pub fn len(&self) -> usize {
         self.chunk_ids.len()
     }
 
+    /// Return iterator over the metadata chunk identifiers.
     pub fn chunk_ids(&self) -> impl Iterator<Item = &ChunkId> {
         self.chunk_ids.iter()
     }
 
+    /// Convert generation chunk to a data chunk.
     pub fn to_data_chunk(&self, ended: &str) -> Result<DataChunk, GenerationChunkError> {
         let json: String =
             serde_json::to_string(self).map_err(GenerationChunkError::JsonGenerate)?;
-- 
cgit v1.2.1