diff options
author | Lars Wirzenius <liw@liw.fi> | 2020-11-28 14:30:48 +0200 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2020-11-28 14:30:48 +0200 |
commit | 93a26490391605a2edeacec06f84b2463d31b0d6 (patch) | |
tree | cd41f167da2714acfe45d3314a6f65dc2004c56f | |
parent | f88bc8e727141cf90b5053d92cf3b3a84d88ae59 (diff) | |
download | summain-rs-93a26490391605a2edeacec06f84b2463d31b0d6.tar.gz |
doc: add doc comments
Also, rename struct to ManifestEntry.
-rw-r--r-- | src/bin/summain.rs | 4 | ||||
-rw-r--r-- | src/lib.rs | 44 |
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(()) } @@ -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(), |