improve docs (#450)

git-refspec/src/lib.rs

@@ -1,7 +1,8 @@
-//! Parse [ref specs]() and represent them.
+//! Parse git ref-specs and represent them.
 #![forbid(unsafe_code, rust_2018_idioms)]
-#![allow(missing_docs)]
+#![deny(missing_docs)]
 
+///
 pub mod parse;
 pub use parse::function::parse;
 

git-refspec/src/parse.rs

@@ -1,4 +1,6 @@
+/// The error returned by the [`parse()`][crate::parse()] function.
 #[derive(Debug, thiserror::Error)]
+#[allow(missing_docs)]
 pub enum Error {
     #[error("Empty refspecs are invalid")]
     Empty,

git-refspec/src/spec.rs

@@ -1,6 +1,25 @@
 use crate::types::Push;
 use crate::{Fetch, Instruction, Mode, Operation, RefSpec, RefSpecRef};
 
+/// Conversion. Use the [RefSpecRef][RefSpec::to_ref()] type for more usage options.
+impl RefSpec {
+    /// Return ourselves as reference type.
+    pub fn to_ref(&self) -> RefSpecRef<'_> {
+        RefSpecRef {
+            mode: self.mode,
+            op: self.op,
+            src: self.src.as_ref().map(|b| b.as_ref()),
+            dst: self.dst.as_ref().map(|b| b.as_ref()),
+        }
+    }
+}
+
+impl Into<RefSpec> for RefSpecRef<'_> {
+    fn into(self) -> RefSpec {
+        self.to_owned()
+    }
+}
+
 /// Access
 impl RefSpecRef<'_> {
     /// Return the refspec mode.

git-refspec/src/types.rs

@@ -20,9 +20,12 @@ pub enum Operation {
     Fetch,
 }
 
+/// Tells what to do and is derived from a [`RefSpec`][RefSpecRef].
 #[derive(PartialEq, Eq, Copy, Clone, Hash, Debug)]
 pub enum Instruction<'a> {
+    /// An instruction for pushing.
     Push(Push<'a>),
+    /// An instruction for fetching.
     Fetch(Fetch<'a>),
 }
 
@@ -56,6 +59,7 @@ pub enum Push<'a> {
 /// Destinations can only be a partial or full ref-names on the local side.
 #[derive(PartialEq, Eq, Copy, Clone, Hash, Debug)]
 pub enum Fetch<'a> {
+    /// Fetch a ref or refs and write the result into the `FETCH_HEAD` without updating local branches.
     Only {
         /// The ref name to fetch on the remote side, without updating the local side. This will write the result into `FETCH_HEAD`.
         src: &'a BStr,
@@ -65,6 +69,7 @@ pub enum Fetch<'a> {
         /// A single partial or full ref name to exclude on the remote, or a pattern with a single `*`. It cannot be a spelled out object hash.
         src: &'a BStr,
     },
+    /// Fetch from `src` and update the corresponding destination branches in `dst` accordingly.
     AndUpdate {
         /// The ref name to fetch on the remote side, or a pattern with a single `*` to match against.
         src: &'a BStr,
@@ -77,6 +82,7 @@ pub enum Fetch<'a> {
 }
 
 impl Instruction<'_> {
+    /// Derive the mode of operation from this instruction.
     pub fn operation(&self) -> Operation {
         match self {
             Instruction::Push(_) => Operation::Push,