diff --git a/radicle/src/git.rs b/radicle/src/git.rs
index 2f1c56c9..5caff29b 100644
--- a/radicle/src/git.rs
+++ b/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,