improve docs and use 'new-style' in error messages.

git-attributes/src/lib.rs

@@ -77,7 +77,7 @@ pub struct NameRef<'a>(&'a str);
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct Assignment {
-    /// The name of the attribute.
+    /// The validated name of the attribute.
     pub name: Name,
     /// The state of the attribute.
     pub state: State,

git-pathspec/src/lib.rs

@@ -5,22 +5,25 @@
 
 use bitflags::bitflags;
 use bstr::BString;
-use git_attributes::Assignment;
 
 ///
 pub mod parse;
 
-/// The output of a pathspec parsing operation. It can be used to match against a path / multiple paths.
+/// The output of a pathspec [parsing][parse()] operation. It can be used to match against a one or more paths.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 pub struct Pattern {
     /// The path part of a pathspec.
+    ///
+    /// `:(top,literal,icase,attr,exclude)some/path` would yield `some/path`.
     pub path: BString,
     /// All magic signatures that were included in the pathspec.
     pub signature: MagicSignature,
     /// The search mode of the pathspec.
     pub search_mode: MatchMode,
     /// All attributes that were included in the `ATTR` part of the pathspec, if present.
-    pub attributes: Vec<Assignment>,
+    ///
+    /// `:(attr:a=one b=):path` would yield attribute `a` and `b`.
+    pub attributes: Vec<git_attributes::Assignment>,
 }
 
 bitflags! {
@@ -43,7 +46,7 @@ pub enum MatchMode {
     ///
     /// See [`PathAwareGlob`][MatchMode::PathAwareGlob] for the alternative.
     ShellGlob,
-    /// Special characters in the pattern, like `*` or `?`, are treated literally
+    /// Special characters in the pattern, like `*` or `?`, are treated literally, effectively turning off globbing.
     Literal,
     /// A single `*` will not match a `/` in the pattern, but a `**` will
     PathAwareGlob,

git-pathspec/src/parse.rs

@@ -6,17 +6,17 @@ use std::borrow::Cow;
 #[derive(thiserror::Error, Debug)]
 #[allow(missing_docs)]
 pub enum Error {
-    #[error("Empty string is not a valid pathspec")]
+    #[error("An empty string is not a valid pathspec")]
     EmptyString,
-    #[error("Found {:?} in signature, which is not a valid keyword", keyword)]
+    #[error("Found {keyword:?} in signature, which is not a valid keyword")]
     InvalidKeyword { keyword: BString },
-    #[error("Unimplemented short keyword: {:?}", short_keyword)]
+    #[error("Unimplemented short keyword: {short_keyword:?}")]
     Unimplemented { short_keyword: char },
     #[error("Missing ')' at the end of pathspec signature")]
     MissingClosingParenthesis,
-    #[error("Attribute has non-ascii characters or starts with '-': {:?}", attribute)]
+    #[error("Attribute has non-ascii characters or starts with '-': {attribute:?}")]
     InvalidAttribute { attribute: BString },
-    #[error("Invalid character in attribute value: {:?}", character)]
+    #[error("Invalid character in attribute value: {character:?}")]
     InvalidAttributeValue { character: char },
     #[error("Escape character '\\' is not allowed as the last character in an attribute value")]
     TrailingEscapeCharacter,