From 995855d9b465498ca0401618d378868ce3b5c993 Mon Sep 17 00:00:00 2001 From: Han Xu Date: Mon, 23 Jan 2023 06:57:19 -0800 Subject: [PATCH] Update doc comments. This patch focuses on the front page of `cargo doc` output. Signed-off-by: Han Xu --- radicle-surf/src/branch.rs | 7 +++--- radicle-surf/src/commit.rs | 48 ++++++++++++++++++++++++++++-------- radicle-surf/src/diff.rs | 7 ------ radicle-surf/src/glob.rs | 2 +- radicle-surf/src/history.rs | 5 ++-- radicle-surf/src/lib.rs | 33 +++++++++++++++---------- radicle-surf/src/repo.rs | 9 ++++--- radicle-surf/src/revision.rs | 48 ------------------------------------ radicle-surf/src/tag.rs | 6 +++-- radicle-surf/t/src/commit.rs | 6 ++--- 10 files changed, 78 insertions(+), 93 deletions(-) diff --git a/radicle-surf/src/branch.rs b/radicle-surf/src/branch.rs index 25001ab..10aca63 100644 --- a/radicle-surf/src/branch.rs +++ b/radicle-surf/src/branch.rs @@ -7,8 +7,7 @@ use git_ref_format::{component, lit, Component, Qualified, RefStr, RefString}; use crate::refs::refstr_join; -/// A `Branch` represents any git branch. This can either be a reference -/// that is under the `refs/heads` or `refs/remotes` namespace. +/// A `Branch` represents any git branch. It can be [`Local`] or [`Remote`]. /// /// Note that if a `Branch` is created from a [`git2::Reference`] then /// any `refs/namespaces` will be stripped. @@ -116,7 +115,7 @@ impl Local { /// If the name is qualified with `refs/heads`, this will be /// shortened to the suffix. To get the `Qualified` name again, /// use [`Local::refname`]. - pub fn new(name: R) -> Self + pub(crate) fn new(name: R) -> Self where R: AsRef, { @@ -213,7 +212,7 @@ impl Remote { /// `refs/remotes`, use [`Remote::from_refs_remotes`] instead. /// /// To get the `Qualified` name, use [`Remote::refname`]. - pub fn new(remote: Component, name: R) -> Self + pub(crate) fn new(remote: Component, name: R) -> Self where R: AsRef, { diff --git a/radicle-surf/src/commit.rs b/radicle-surf/src/commit.rs index 272da9f..a4bc9f5 100644 --- a/radicle-surf/src/commit.rs +++ b/radicle-surf/src/commit.rs @@ -17,7 +17,7 @@ use std::{convert::TryFrom, str}; -use git_ext::Oid; +use radicle_git_ext::Oid; use thiserror::Error; #[cfg(feature = "serde")] @@ -33,7 +33,7 @@ pub enum Error { Utf8Error(#[from] str::Utf8Error), } -/// `Author` is the static information of a [`git2::Signature`]. +/// Represents the authorship of actions in a git repo. #[cfg_attr(feature = "serde", derive(Deserialize, Serialize))] #[derive(Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct Author { @@ -49,20 +49,48 @@ pub struct Author { deserialize_with = "deserialize_time" ) )] - pub time: git2::Time, + pub time: Time, +} + +/// Time used in the authorship of an action in a git repo. +#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)] +pub struct Time { + inner: git2::Time, +} + +impl From for Time { + fn from(inner: git2::Time) -> Self { + Self { inner } + } +} + +impl Time { + pub fn new(epoch_seconds: i64, offset_minutes: i32) -> Self { + git2::Time::new(epoch_seconds, offset_minutes).into() + } + + /// Returns the seconds since UNIX epoch. + pub fn seconds(&self) -> i64 { + self.inner.seconds() + } + + /// Returns the timezone offset in minutes. + pub fn offset_minutes(&self) -> i32 { + self.inner.offset_minutes() + } } #[cfg(feature = "serde")] -fn deserialize_time<'de, D>(deserializer: D) -> Result +fn deserialize_time<'de, D>(deserializer: D) -> Result where D: Deserializer<'de>, { let seconds: i64 = Deserialize::deserialize(deserializer)?; - Ok(git2::Time::new(seconds, 0)) + Ok(Time::new(seconds, 0)) } #[cfg(feature = "serde")] -fn serialize_time(t: &git2::Time, serializer: S) -> Result +fn serialize_time(t: &Time, serializer: S) -> Result where S: Serializer, { @@ -91,15 +119,15 @@ impl<'repo> TryFrom> for Author { fn try_from(signature: git2::Signature) -> Result { let name = str::from_utf8(signature.name_bytes())?.into(); let email = str::from_utf8(signature.email_bytes())?.into(); - let time = signature.when(); + let time = signature.when().into(); Ok(Author { name, email, time }) } } -/// `Commit` is the static information of a [`git2::Commit`]. To get back the -/// original `Commit` in the repository we can use the [`Oid`] to retrieve -/// it. +/// `Commit` is the metadata of a [Git commit][git-commit]. +/// +/// [git-commit]: https://git-scm.com/book/en/v2/Git-Internals-Git-Objects #[cfg_attr(feature = "serde", derive(Deserialize))] #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct Commit { diff --git a/radicle-surf/src/diff.rs b/radicle-surf/src/diff.rs index b315fc5..db062a1 100644 --- a/radicle-surf/src/diff.rs +++ b/radicle-surf/src/diff.rs @@ -17,8 +17,6 @@ //! Types that represent diff(s) in a Git repo. -#![allow(dead_code, unused_variables, missing_docs)] - use std::path::PathBuf; #[cfg(feature = "serde")] @@ -262,11 +260,6 @@ impl Serialize for Modification { { use serde::ser::SerializeMap as _; - const NAME: &str = "Modification"; - const ADDITION: &str = "Addition"; - const DELETION: &str = "Deletion"; - const CONTEXT: &str = "Context"; - match self { Modification::Addition(addition) => { let mut map = serializer.serialize_map(Some(3))?; diff --git a/radicle-surf/src/glob.rs b/radicle-surf/src/glob.rs index c474e5a..f06e36c 100644 --- a/radicle-surf/src/glob.rs +++ b/radicle-surf/src/glob.rs @@ -34,7 +34,7 @@ pub enum Error { RefFormat(#[from] git_ref_format::Error), } -/// A collection of globs for T (a git reference type). +/// A collection of globs for a git reference type. #[derive(Clone, Debug)] pub struct Glob { globs: Vec>, diff --git a/radicle-surf/src/history.rs b/radicle-surf/src/history.rs index 692a959..b3af56d 100644 --- a/radicle-surf/src/history.rs +++ b/radicle-surf/src/history.rs @@ -22,8 +22,9 @@ use std::{ use crate::{Commit, Error, Repository, ToCommit}; -/// An iterator that produces the history of commits for a given `head`, -/// in the `repo`. +/// An iterator that produces the history of commits for a given `head`. +/// +/// The lifetime of this struct is attached to the underlying [`Repository`]. pub struct History<'a> { repo: &'a Repository, head: Commit, diff --git a/radicle-surf/src/lib.rs b/radicle-surf/src/lib.rs index 95eb0ed..989319c 100644 --- a/radicle-surf/src/lib.rs +++ b/radicle-surf/src/lib.rs @@ -1,7 +1,7 @@ // This file is part of radicle-git // // -// Copyright (C) 2019-2022 The Radicle Team +// Copyright (C) 2019-2023 The Radicle Team // // This program is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License version 3 or @@ -15,28 +15,35 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -//! `radicle-surf` is a library to describe a Git repository as a file system. -//! It aims to provide an easy-to-use API to browse a repository via the concept -//! of files and directories for any given revision. It also allows the user to -//! diff any two different revisions. +//! `radicle-surf` is a library to help users explore a Git repository with +//! ease. It supports browsing a repository via the concept of files and +//! directories, or via blobs and trees in a git fashion. With the additional +//! support of [`diff::Diff`] and [`History`], this library can be used to build +//! an intuitive UI for any Git repository. //! -//! The main entry point of the API is [Repository]. +//! The main entry point of the library API is [`Repository`]. //! //! Let's start surfing! +//! +//! ## Serialization with feature `serde` +//! +//! Many types in this crate support serialization using [`Serde`][serde] +//! through the `serde` feature flag for this crate. +//! +//! [serde]: https://crates.io/crates/serde -pub extern crate git_ref_format; +/// Re-exports. +pub use git_ref_format; -extern crate radicle_git_ext as git_ext; +/// Represents an object id in Git. Re-exported from `radicle-git-ext`. +pub use radicle_git_ext::Oid; pub mod blob; pub mod diff; pub mod fs; pub mod tree; -// Re-export git2 as sub-module -pub use git2::{self, Error as Git2Error, Time}; -pub use radicle_git_ext::Oid; - +/// Private modules with their public types. mod repo; pub use repo::Repository; @@ -53,7 +60,7 @@ mod tag; pub use tag::Tag; mod commit; -pub use commit::{Author, Commit}; +pub use commit::{Author, Commit, Time}; mod namespace; pub use namespace::Namespace; diff --git a/radicle-surf/src/repo.rs b/radicle-surf/src/repo.rs index 2f0e2f9..48c9e8b 100644 --- a/radicle-surf/src/repo.rs +++ b/radicle-surf/src/repo.rs @@ -57,10 +57,13 @@ pub mod error { } } -/// Wrapper around the `git2`'s `git2::Repository` type. -/// This is to to limit the functionality that we can do -/// on the underlying object. +/// Represents the state associated with a Git repository. +/// +/// Many other types in this crate are derived from methods in this struct. pub struct Repository { + /// Wrapper around the `git2`'s `git2::Repository` type. + /// This is to to limit the functionality that we can do + /// on the underlying object. inner: git2::Repository, } diff --git a/radicle-surf/src/revision.rs b/radicle-surf/src/revision.rs index 1dac0dc..594f9f8 100644 --- a/radicle-surf/src/revision.rs +++ b/radicle-surf/src/revision.rs @@ -15,54 +15,6 @@ // You should have received a copy of the GNU General Public License // along with this program. If not, see . -//! ``` -//! use nonempty::NonEmpty; -//! use radicle_surf::file_system::{Directory, File, Label, Path, SystemType}; -//! use radicle_surf::file_system::unsound; -//! use radicle_surf::vcs::git::*; -//! use std::collections::HashMap; -//! use std::str::FromStr; -//! # use std::error::Error; -//! -//! # fn main() -> Result<(), Box> { -//! let repo = Repository::new("./data/git-platinum")?; -//! -//! // Pin the browser to a parituclar commit. -//! let pin_commit = Oid::from_str("3873745c8f6ffb45c990eb23b491d4b4b6182f95")?; -//! let mut browser = Browser::new(&repo, Branch::local("master"))?; -//! browser.commit(pin_commit)?; -//! -//! let directory = browser.get_directory()?; -//! let mut directory_contents = directory.list_directory(); -//! directory_contents.sort(); -//! -//! assert_eq!(directory_contents, vec![ -//! SystemType::file(unsound::label::new(".i-am-well-hidden")), -//! SystemType::file(unsound::label::new(".i-too-am-hidden")), -//! SystemType::file(unsound::label::new("README.md")), -//! SystemType::directory(unsound::label::new("bin")), -//! SystemType::directory(unsound::label::new("src")), -//! SystemType::directory(unsound::label::new("text")), -//! SystemType::directory(unsound::label::new("this")), -//! ]); -//! -//! // find src directory in the Git directory and the in-memory directory -//! let src_directory = directory -//! .find_directory(Path::new(unsound::label::new("src"))) -//! .expect("failed to find src"); -//! let mut src_directory_contents = src_directory.list_directory(); -//! src_directory_contents.sort(); -//! -//! assert_eq!(src_directory_contents, vec![ -//! SystemType::file(unsound::label::new("Eval.hs")), -//! SystemType::file(unsound::label::new("Folder.svelte")), -//! SystemType::file(unsound::label::new("memory.rs")), -//! ]); -//! # -//! # Ok(()) -//! # } -//! ``` - use std::{convert::Infallible, str::FromStr}; use git_ref_format::{Qualified, RefString}; diff --git a/radicle-surf/src/tag.rs b/radicle-surf/src/tag.rs index c402b79..1319933 100644 --- a/radicle-surf/src/tag.rs +++ b/radicle-surf/src/tag.rs @@ -1,11 +1,13 @@ use std::{convert::TryFrom, str}; -use git_ext::Oid; use git_ref_format::{component, lit, Qualified, RefStr, RefString}; +use radicle_git_ext::Oid; use crate::{refs::refstr_join, Author}; -/// The static information of a [`git2::Tag`]. +/// The metadata of a [`Git tag`][git-tag]. +/// +/// [git-tag]: https://git-scm.com/book/en/v2/Git-Basics-Tagging #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)] pub enum Tag { /// A light-weight git tag. diff --git a/radicle-surf/t/src/commit.rs b/radicle-surf/t/src/commit.rs index 4519d77..b0a7222 100644 --- a/radicle-surf/t/src/commit.rs +++ b/radicle-surf/t/src/commit.rs @@ -2,7 +2,7 @@ use std::str::FromStr; use proptest::prelude::*; use radicle_git_ext::Oid; -use radicle_surf::{Author, Commit}; +use radicle_surf::{Author, Commit, Time}; use test_helpers::roundtrip; proptest! { @@ -18,12 +18,12 @@ fn commits_strategy() -> impl Strategy { author: Author { name: text.clone(), email: text.clone(), - time: git2::Time::new(time, 0), + time: Time::new(time, 0), }, committer: Author { name: text.clone(), email: text.clone(), - time: git2::Time::new(time, 0), + time: Time::new(time, 0), }, message: text.clone(), summary: text,