Update public API docs

src/data_request.rs

@@ -2,21 +2,54 @@
 
 /// A type that describes which components of a UFO should be loaded.
 ///
-/// By default, we load all components of the UFO file; however if you only
-/// need some subset of these, you can pass this struct to [`Ufo::with_fields`]
-/// in order to only load the fields specified in this object. This can help a
-/// lot with performance with large UFO files if you don't need the glyph data.
+/// By default, all components of the UFO file are loaded; however, if you only
+/// need a subset of them, you can pass this struct to [`Ufo::with_fields`] in
+/// order to only load the fields you specify. This can improve performance in
+/// large projects.
+///
+/// # Examples
+///
+/// A [DataRequest] that excludes all layer, glyph and kerning data:
+///
+/// ```
+/// use norad::DataRequest;
+///
+/// let datareq = DataRequest::default().layers(false).kerning(false);
+/// ```
+///
+/// A [DataRequest] that excludes all UFO data and images:
+///
+/// ```
+/// use norad::DataRequest;
+///
+/// let datareq = DataRequest::default().data(false).images(false);
+/// ```
+///
+/// A [DataRequest] that only includes parsed lib.plist data:
+///
+/// ```
+/// use norad::DataRequest;
+///
+/// let datareq = DataRequest::none().lib(true);
+/// ```
 ///
 /// [`Ufo::with_fields`]: struct.Ufo.html#method.with_fields
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[non_exhaustive]
 pub struct DataRequest {
+    /// Load and parse all layers and glyphs.
     pub layers: bool,
+    /// Load parsed lib.plist data
     pub lib: bool,
+    /// Load parsed groups.plist data
     pub groups: bool,
+    /// Load parsed kerning.plist data
     pub kerning: bool,
+    /// Load Adobe .fea format feature file data
     pub features: bool,
+    /// Load data
     pub data: bool,
+    /// Load images
     pub images: bool,
 }
 
@@ -25,17 +58,17 @@ impl DataRequest {
         DataRequest { layers: b, lib: b, groups: b, kerning: b, features: b, data: b, images: b }
     }
 
-    /// Returns a `DataRequest` requesting all UFO data.
+    /// Returns a [`DataRequest`] requesting all UFO data.
     pub fn all() -> Self {
         DataRequest::from_bool(true)
     }
 
-    /// Returns a `DataRequest` requesting no UFO data.
+    /// Returns a [`DataRequest`] requesting no UFO data.
     pub fn none() -> Self {
         DataRequest::from_bool(false)
     }
 
-    /// Request that returned UFO data include the glyph layers and points.
+    /// Request that returned UFO data include layers and their glyph data.
     pub fn layers(mut self, b: bool) -> Self {
         self.layers = b;
         self
@@ -59,8 +92,8 @@ impl DataRequest {
         self
     }
 
-    /// Request that returned UFO data include OpenType Layout features in Adobe
-    /// .fea format.
+    /// Request that returned UFO data include [OpenType Layout features in Adobe
+    /// .fea format](https://unifiedfontobject.org/versions/ufo3/features.fea/).
     pub fn features(mut self, b: bool) -> Self {
         self.features = b;
         self

src/datastore.rs

@@ -24,7 +24,9 @@ use crate::Error;
 /// file. Images must always be in a flat directory. The paths are always relative to
 /// a UFO's data directory.
 ///
-/// # Example
+/// This type supports partial equality testing that is based on path comparisons.
+///
+/// # Examples
 ///
 /// Consider a UFO on disk with the following structure:
 ///
@@ -75,13 +77,15 @@ pub struct Store<T> {
 #[doc(hidden)]
 pub struct Data;
 
+/// Lazy access to the contents of the UFO's `data` directory.
 pub type DataStore = Store<Data>;
 
 /// Implements custom behavior for the images store.
 #[derive(Debug, Default, Clone)]
 #[doc(hidden)]
 pub struct Image;
 
+/// Lazy access to the contents of the UFO's `images` directory.
 pub type ImageStore = Store<Image>;
 
 /// Defines custom behavior for data and images stores.
@@ -122,7 +126,7 @@ where
     }
 }
 
-/// Implements partial equality testing by just comparing paths.
+/// Implements path testing-based partial equality for [Store<T>].
 impl<T: DataType> PartialEq for Store<T> {
     fn eq(&self, other: &Self) -> bool {
         self.items.len() == other.items.len()
@@ -275,7 +279,7 @@ impl<T: DataType> Store<T> {
         self.items.is_empty()
     }
 
-    /// An iterator visiting all paths in arbitrary order.
+    /// Returns an iterator visiting all paths in arbitrary order.
     pub fn keys(&self) -> impl Iterator<Item = &PathBuf> {
         self.items.keys()
     }
@@ -317,7 +321,7 @@ impl<T: DataType> Store<T> {
         }
     }
 
-    /// Try to insert data for this path. Overwrites an existing data.
+    /// Try to insert data for this path. Overwrites existing data.
     ///
     /// Does not return the overwritten data, use [`Self::get`] first to get it if you need
     /// it.

src/error.rs

@@ -17,35 +17,65 @@ pub enum Error {
     /// An error returned when trying to save a Glyph that contains a `public.objectLibs`
     /// lib key already (the key is automatically managed by Norad).
     PreexistingPublicObjectLibsKey,
+    /// An error returned when there is no default layer in the UFO directory.
     MissingDefaultLayer,
+    /// An error returned when an expected layer is missing.
     MissingLayer(String),
+    /// An error returned when a layer is duplicated.
     DuplicateLayer(String),
+    /// An error returned when there is an invalid color definition.
     InvalidColor(InvalidColorString),
+    /// An error returned when there is a duplicate glyph.
     DuplicateGlyph {
+        /// The layer name.
         layer: String,
+        /// The glyph name.
         glyph: String,
     },
+    /// An error returned when there is a missing expected glyph
     MissingGlyph {
+        /// The layer name.
         layer: String,
+        /// The glyph name.
         glyph: String,
     },
+    /// An error returned when there is an input/output problem during processing
     IoError(IoError),
+    /// An error returned when there is an XML parsing problem.
     ParseError(XmlError),
+    /// An error that wraps a [GlifError].
     Glif(GlifError),
+    /// An error that wraps a [GlifWriteError].
     GlifWrite(GlifWriteError),
+    /// An error that wraps a [PlistError].
     PlistError(PlistError),
+    /// An error returned when there is invalid fontinfo.plist data.
     InvalidFontInfo,
+    /// An error returned when there is a problem during fontinfo.plist version up-conversion.
     FontInfoUpconversion,
+    /// An error returned when there is invalid groups.plist data.
     InvalidGroups(GroupsValidationError),
+    /// An error returned when there is a problem during groups.plist version up-conversion.
     GroupsUpconversionFailure(GroupsValidationError),
-    // the string is the key
+    /// An error returned when there is a problem parsing plist data into
+    /// [`plist::Dictionary`] types.
+    ///
+    /// The string is the dictionary key.
     ExpectedPlistDictionary(String),
+    /// An error returned when there is an unexpected plist string.
     ExpectedPlistString,
+    /// An error returned when there is an inappropriate negative sign on a value.
     ExpectedPositiveValue,
+    /// An error returned when there is a problem with kurbo contour conversion.
     #[cfg(feature = "kurbo")]
     ConvertContour(ErrorKind),
+    /// An error returned when there is a missing mandatory file.
     MissingFile(String),
+    /// An error returned when the requested UFO directory path is not present.
     MissingUfoDir(String),
+    /// An error returned when there is an invalid entry in an image or data store.
+    ///
+    /// This error wraps a [`StoreError`] type and provides additional path data.
     InvalidStoreEntry(PathBuf, StoreError),
 }
 
@@ -74,15 +104,23 @@ pub enum StoreError {
 /// An error representing a failure to validate UFO groups.
 #[derive(Debug)]
 pub enum GroupsValidationError {
+    /// An error returned when there is an invalid groups name.
     InvalidName,
-    OverlappingKerningGroups { glyph_name: String, group_name: String },
+    /// An error returned when there are overlapping kerning groups.
+    OverlappingKerningGroups {
+        /// The glyph name.
+        glyph_name: String,
+        /// The group name.
+        group_name: String,
+    },
 }
 
-/// A [`Color`] string was invalid.
+/// An error representing an invalid [`Color`] string.
 ///
 /// [`Color`]: crate::Color
 #[derive(Debug)]
 pub struct InvalidColorString {
+    /// The source string that caused the error.
     source: String,
 }
 
@@ -92,15 +130,19 @@ impl InvalidColorString {
     }
 }
 
-/// An error that occurs while parsing a .glif file
+/// An error representing a failure during .glif file parsing.
 #[derive(Debug)]
 pub struct GlifError {
+    /// The glif file path.
     pub path: Option<PathBuf>,
+    /// The buffer position.
     pub position: usize,
+    /// The kind of error.
     pub kind: ErrorKind,
 }
 
-/// An error when attempting to write a .glif file
+/// An error representing a failure during .glif file serialization. This
+/// error wraps [GlyphName] and [WriteError] types.
 #[derive(Debug)]
 pub struct GlifWriteError {
     /// The name of the glif where the error occured.
@@ -113,19 +155,22 @@ pub struct GlifWriteError {
 /// out a .glif type.
 #[derive(Debug)]
 pub enum WriteError {
+    /// XML serialzation error. Wraps a [XmlError].
     Xml(XmlError),
     /// When writing out the 'lib' section, we use the plist crate to generate
     /// the plist xml, and then strip the preface and closing </plist> tag.
     ///
     /// If for some reason the implementation of that crate changes, we could
     /// be affected, although this is very unlikely.
     InternalLibWriteError,
+    /// Generic serialization error.  Wraps an [IoError].
     IoError(IoError),
+    /// Plist serialization error. Wraps a [PlistError].
     Plist(PlistError),
 }
 
 /// Errors that happen when parsing `glif` files. This is converted into either
-/// `Error::Xml` or `Error::Glif` at the parse boundary.
+/// `Error::ParseError` or `Error::Glif` at the parse boundary.
 #[derive(Debug)]
 pub(crate) enum GlifErrorInternal {
     /// A problem with the xml data.
@@ -137,38 +182,71 @@ pub(crate) enum GlifErrorInternal {
 /// The reason for a glif parse failure.
 #[derive(Debug, Clone, Copy)]
 pub enum ErrorKind {
+    /// The glif version is not supported by this library.
     UnsupportedGlifVersion,
+    /// An unknown point type.
     UnknownPointType,
+    /// The first XML element of a glif file is invalid.
     WrongFirstElement,
+    /// Missing a close tag.
     MissingCloseTag,
+    /// Has an unexpected tag.
     UnexpectedTag,
+    /// Has an invalid hexadecimal value.
     BadHexValue,
+    /// Has an invalid numeric value.
     BadNumber,
+    /// Has an invalid color value.
     BadColor,
+    /// Has an invalid anchor definition.
     BadAnchor,
+    /// Has an invalid point definition.
     BadPoint,
+    /// Has an invalid guideline definition.
     BadGuideline,
+    /// Has an invalid component definition.
     BadComponent,
+    /// Has an invalid image definition.
     BadImage,
+    /// Has an invalid identifier.
     BadIdentifier,
+    /// Has an invalid lib.
     BadLib,
+    /// Has an unexected duplicate value.
     UnexpectedDuplicate,
+    /// Has an unexpected move definition.
     UnexpectedMove,
+    /// Has an unexpected smooth definition.
     UnexpectedSmooth,
+    /// Has an unexpected element definition.
     UnexpectedElement,
+    /// Has an unexpected attribute definition.
     UnexpectedAttribute,
+    /// Has an unexpected end of file definition.
     UnexpectedEof,
+    /// Has an unexpected point following an off curve point definition.
     UnexpectedPointAfterOffCurve,
+    /// Has too many off curve points in sequence.
     TooManyOffCurves,
+    /// The contour pen path was not started
     PenPathNotStarted,
+    /// Has trailing off curve points defined.
     TrailingOffCurves,
+    /// Has duplicate identifiers.
     DuplicateIdentifier,
+    /// Has unexepected drawing data.
     UnexpectedDrawing,
+    /// Has incomplete drawing data.
     UnfinishedDrawing,
+    /// Has an unexpected point field.
     UnexpectedPointField,
+    /// Has an unexpected component field.
     UnexpectedComponentField,
+    /// Has an unexpected anchor field.
     UnexpectedAnchorField,
+    /// Has an unexpected guideline field.
     UnexpectedGuidelineField,
+    /// Has an unexpected image field.
     UnexpectedImageField,
 }
 
@@ -268,7 +346,7 @@ impl std::fmt::Display for ErrorKind {
         match self {
             ErrorKind::UnsupportedGlifVersion => write!(f, "Unsupported glif version"),
             ErrorKind::UnknownPointType => write!(f, "Unknown point type"),
-            ErrorKind::WrongFirstElement => write!(f, "Wrong first element"),
+            ErrorKind::WrongFirstElement => write!(f, "Wrong first XML element in glif file"),
             ErrorKind::MissingCloseTag => write!(f, "Missing close tag"),
             ErrorKind::UnexpectedTag => write!(f, "Unexpected tag"),
             ErrorKind::BadHexValue => write!(f, "Bad hex value"),