6598243 radicle: document `parse_ref` and `parse_ref_namespaced` — heartwood

Radicle Heartwood Protocol & Stack

radicle: document `parse_ref` and `parse_ref_namespaced`

Fintan Halpenny committed 1 year ago

commit 65982434658b88f5d4ed4e93bef3964e7eb5b645
parent 41c33901ff6a70e87e649ba61c5d52c84f661ed1

1 file changed +28 -2

modified radicle/src/git.rs

@@ -438,7 +438,19 @@ pub fn remote_refs(url: &Url) -> Result<RandomMap<RemoteId, Refs>, ListRefsError

     Ok(remotes)
 }
 /// Parse a ref string. Returns an error if it isn't namespaced.
 /// Parse a [`format::Qualified`] reference string while expecting the reference
 /// to start with `refs/namespaces`. If the namespace is not present, then an
 /// error will be returned.
 ///
 /// The namespace returned is the path component that is after `refs/namespaces`,
 /// e.g. in the reference below, the segment is
 /// `z6MkvUJtYD9dHDJfpevWRT98mzDDpdAtmUjwyDSkyqksUr7C`:
 ///
 ///     refs/namespaces/z6MkvUJtYD9dHDJfpevWRT98mzDDpdAtmUjwyDSkyqksUr7C/refs/heads/main
 ///
 /// The `T` can be specified when calling the function. For example, if you
 /// wanted to parse the namespace as a `PublicKey`, then you would the function
 /// like so, `parse_ref_namespaced::<PublicKey>(s)`.
 pub fn parse_ref_namespaced<T>(s: &str) -> Result<(T, format::Qualified), RefError>
 where
     T: FromStr,

@@ -451,7 +463,21 @@ where

     }
 }
 /// Parse a ref string. Optionally returns a namespace.
 /// Parse a [`format::Qualified`] reference string. It will optionally return
 /// the namespace, if present.
 ///
 /// The qualified form could be of the form: `refs/heads/main`,
 /// `refs/tags/v1.0`, etc.
 ///
 /// The namespace returned is the path component that is after `refs/namespaces`,
 /// e.g. in the reference below, the segment is
 /// `z6MkvUJtYD9dHDJfpevWRT98mzDDpdAtmUjwyDSkyqksUr7C`:
 ///
 ///     refs/namespaces/z6MkvUJtYD9dHDJfpevWRT98mzDDpdAtmUjwyDSkyqksUr7C/refs/heads/main
 ///
 /// The `T` can be specified when calling the function. For example, if you
 /// wanted to parse the namespace as a `PublicKey`, then you would the function
 /// like so, `parse_ref::<PublicKey>(s)`.
 pub fn parse_ref<T>(s: &str) -> Result<(Option<T>, format::Qualified), RefError>
 where
     T: FromStr,