Merge remote-tracking branch 'han/doc-update'

* han/doc-update:
  Update doc comments.

Signed-off-by: Fintan Halpenny <fintan.halpenny@gmail.com>

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

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 {

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

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

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,

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;

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

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};

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.

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,