summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLars Wirzenius <liw@liw.fi>2020-11-28 14:30:48 +0200
committerLars Wirzenius <liw@liw.fi>2020-11-28 14:30:48 +0200
commit93a26490391605a2edeacec06f84b2463d31b0d6 (patch)
treecd41f167da2714acfe45d3314a6f65dc2004c56f
parentf88bc8e727141cf90b5053d92cf3b3a84d88ae59 (diff)
downloadsummain-rs-93a26490391605a2edeacec06f84b2463d31b0d6.tar.gz
doc: add doc comments
Also, rename struct to ManifestEntry.
-rw-r--r--src/bin/summain.rs4
-rw-r--r--src/lib.rs44
2 files changed, 44 insertions, 4 deletions
diff --git a/src/bin/summain.rs b/src/bin/summain.rs
index f25b857..056bc8b 100644
--- a/src/bin/summain.rs
+++ b/src/bin/summain.rs
@@ -2,7 +2,7 @@ use anyhow::Context;
use std::fs::symlink_metadata;
use std::path::{Path, PathBuf};
use structopt::StructOpt;
-use summain::Entry;
+use summain::ManifestEntry;
fn main() -> anyhow::Result<()> {
let mut opt = Opt::from_args();
@@ -21,7 +21,7 @@ struct Opt {
fn report(pathname: &Path) -> anyhow::Result<()> {
let m = symlink_metadata(pathname)?;
- let e = Entry::new(pathname, m);
+ let e = ManifestEntry::new(pathname, m);
println!("{}", serde_yaml::to_string(&e)?);
Ok(())
}
diff --git a/src/lib.rs b/src/lib.rs
index bdf5bed..eacce62 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,10 +1,44 @@
+//! File manifests.
+//!
+//! This crate defines the [`ManifestEntry`] struct to represent an
+//! entry in a file manifest. The entry contains data about each file.
+//! A manifest can be produced of some data, and later, a new manifest
+//! can be produced and compared with the original. If the manifests
+//! have changed, the data has changed. If they haven't changed, the
+//! data has probably not changed.
+//!
+//! Such manifests can be used, for example, to verify that data that
+//! has been restored from a backup is the same as what was backed up.
+//!
+//! This crate uses Linux metadata of files.
+//!
+//! ~~~
+//! let m = std::fs::metadata(".").unwrap();
+//! let e = summain::ManifestEntry(m);
+//! println!("{}", serde_yaml::to_string(e).unwrap());
+//! ~~~
+//!
+//! The output is something like:
+//!
+//! ~~~yaml
+//! path: "."
+//! atime: 1606565868
+//! atime_nsec: 824368155
+//! mode: drwxrwxr-x
+//! mtime: 1606565867
+//! mtime_nsec: 500355545
+//! nlink: 6
+//! size: ~
+//! ~~~
+
use serde::Serialize;
use std::fs::Metadata;
use std::os::linux::fs::MetadataExt;
use std::path::{Path, PathBuf};
+/// An entry in a file manifest.
#[derive(Serialize, Debug)]
-pub struct Entry {
+pub struct ManifestEntry {
path: PathBuf,
atime: i64,
atime_nsec: i64,
@@ -16,7 +50,13 @@ pub struct Entry {
size: Option<u64>,
}
-impl Entry {
+impl ManifestEntry {
+ /// Create a new manifest entry.
+ ///
+ /// The pathname of the file and the metadata are passed in by the
+ /// caller. This function doesn't query the system for it.
+ ///
+ /// The structure can be serialized using serde.
pub fn new(path: &Path, m: Metadata) -> Self {
Self {
path: path.to_path_buf(),