frost/bdk
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add documentation fixes

Browse Source
This commit is contained in:
rajarshimaitra
2023-03-10 23:23:29 +05:30
committed by 志宇
parent cd4945af3a
commit 24df03afd6
21 changed files with 316 additions and 316 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
crates/file_store/src/file_store.rs
View File

@@ -1,6 +1,6 @@
//! Module for persisting data on-disk.
//! Module for persisting data on disk.
//!
//! The star of the show is [`KeychainStore`] which maintains an append-only file of
//! The star of the show is [`KeychainStore`], which maintains an append-only file of
//! [`KeychainChangeSet`]s which can be used to restore a [`KeychainTracker`].
use bdk_chain::{
keychain::{KeychainChangeSet, KeychainTracker},
@@ -40,7 +40,7 @@ where
{
/// Creates a new store from a [`File`].
///
/// The file must have been opened with read, write permissions.
/// The file must have been opened with read and write permissions.
///
/// [`File`]: std::fs::File
pub fn new(mut file: File) -> Result<Self, FileError> {
@@ -59,7 +59,7 @@ where
})
}
/// Creates or loads a a store from `db_path`. If no file exists there it will be created.
/// Creates or loads a store from `db_path`. If no file exists there, it will be created.
pub fn new_from_path<D: AsRef<Path>>(db_path: D) -> Result<Self, FileError> {
let already_exists = db_path.as_ref().exists();
@@ -76,15 +76,15 @@ where
Self::new(db_file)
}
/// Iterates over the stored changeset from first to last changing the seek position at each
/// Iterates over the stored changeset from first to last, changing the seek position at each
/// iteration.
///
/// The iterator may fail to read an entry and therefore return an error. However the first time
/// it returns an error will be the last. After doing so the iterator will always yield `None`.
/// The iterator may fail to read an entry and therefore return an error. However, the first time
/// it returns an error will be the last. After doing so, the iterator will always yield `None`.
///
/// **WARNING**: This method changes the write position in the underlying file. You should
/// always iterate over all entries until `None` is returned if you want your next write to go
/// at the end, otherwise you will write over existing enties.
/// at the end; otherwise, you will write over existing entries.
pub fn iter_changesets(&mut self) -> Result<EntryIter<'_, KeychainChangeSet<K, P>>, io::Error> {
self.db_file
.seek(io::SeekFrom::Start(MAGIC_BYTES_LEN as _))?;
@@ -94,13 +94,13 @@ where
/// Loads all the changesets that have been stored as one giant changeset.
///
/// This function returns a tuple of the aggregate changeset and a result which indicates
/// This function returns a tuple of the aggregate changeset and a result that indicates
/// whether an error occurred while reading or deserializing one of the entries. If so the
/// changeset will consist of all of those it was able to read.
///
/// You should usually check the error. In many applications it may make sense to do a full
/// wallet scan with a stop gap after getting an error since it is likely that one of the
/// changesets it was unable to read changed the derivation indicies of the tracker.
/// You should usually check the error. In many applications, it may make sense to do a full
/// wallet scan with a stop-gap after getting an error, since it is likely that one of the
/// changesets it was unable to read changed the derivation indices of the tracker.
///
/// **WARNING**: This method changes the write position of the underlying file. The next
/// changeset will be written over the erroring entry (or the end of the file if none existed).
@@ -117,7 +117,7 @@ where
(changeset, result)
}
/// Reads and applies all the changesets stored sequentially to tracker, stopping when it fails
/// Reads and applies all the changesets stored sequentially to the tracker, stopping when it fails
/// to read the next one.
///
/// **WARNING**: This method changes the write position of the underlying file. The next
@@ -132,9 +132,9 @@ where
Ok(())
}
/// Append a new changeset to the file and truncate file to the end of the appended changeset.
/// Append a new changeset to the file and truncate the file to the end of the appended changeset.
///
/// The truncation is to avoid the possibility of having a valid, but inconsistent changeset
/// The truncation is to avoid the possibility of having a valid but inconsistent changeset
/// directly after the appended changeset.
pub fn append_changeset(
&mut self,
@@ -153,12 +153,12 @@ where
// truncate file after this changeset addition
// if this is not done, data after this changeset may represent valid changesets, however
// applying those changesets on top of this one may result in inconsistent state
// applying those changesets on top of this one may result in an inconsistent state
let pos = self.db_file.stream_position()?;
self.db_file.set_len(pos)?;
// We want to make sure that derivation indexe changes are written to disk as soon as
// possible so you know about the write failure before you give ou the address in the application.
// We want to make sure that derivation indices changes are written to disk as soon as
// possible, so you know about the write failure before you give out the address in the application.
if !changeset.derivation_indices.is_empty() {
self.db_file.sync_data()?;
}
@@ -172,7 +172,7 @@ where
pub enum FileError {
/// IO error, this may mean that the file is too short.
Io(io::Error),
/// Magic bytes do not match expected.
/// Magic bytes do not match what is expected.
InvalidMagicBytes([u8; MAGIC_BYTES_LEN]),
}
@@ -200,9 +200,9 @@ impl std::error::Error for FileError {}
/// Error type for [`EntryIter`].
#[derive(Debug)]
pub enum IterError {
/// Failure to read from file.
/// Failure to read from the file.
Io(io::Error),
/// Failure to decode data from file.
/// Failure to decode data from the file.
Bincode(bincode::ErrorKind),
}