995855d Update doc comments. — radicle-git

modified 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<R>(name: R) -> Self
     pub(crate) fn new<R>(name: R) -> Self
     where
         R: AsRef<RefStr>,
     {

@@ -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<R>(remote: Component, name: R) -> Self
     pub(crate) fn new<R>(remote: Component, name: R) -> Self
     where
         R: AsRef<RefStr>,
     {

modified 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<git2::Time> 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<git2::Time, D::Error>
 fn deserialize_time<'de, D>(deserializer: D) -> Result<Time, D::Error>
 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<S>(t: &git2::Time, serializer: S) -> Result<S::Ok, S::Error>
 fn serialize_time<S>(t: &Time, serializer: S) -> Result<S::Ok, S::Error>
 where
     S: Serializer,
 {

@@ -91,15 +119,15 @@ impl<'repo> TryFrom<git2::Signature<'repo>> for Author {

     fn try_from(signature: git2::Signature) -> Result<Self, Self::Error> {
         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 {

modified 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))?;

modified 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<T> {
     globs: Vec<QualifiedPattern<'static>>,

modified 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,

modified radicle-surf/src/lib.rs

@@ -1,7 +1,7 @@

 // This file is part of radicle-git
 // <https://github.com/radicle-dev/radicle-git>
 //
 // Copyright (C) 2019-2022 The Radicle Team <dev@radicle.xyz>
 // Copyright (C) 2019-2023 The Radicle Team <dev@radicle.xyz>
 //
 // 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 <https://www.gnu.org/licenses/>.
 //! `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;

modified 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,
 }

modified 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 <https://www.gnu.org/licenses/>.
 //! ```
 //! 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<dyn Error>> {
 //! 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};

modified 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.

modified 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<Value = Commit> {

         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,