[librsvg: 9/22] Document make_property! a bit better

[Federico Mena Quintero <federico src gnome org>]

commit 8640591dfd52c7bfb5a123cf87da8ef9c6e41956
Author: Federico Mena Quintero <federico gnome org>
Date:   Thu Jun 25 18:22:45 2020 -0500

    Document make_property! a bit better

 rsvg_internals/src/property_macros.rs | 82 ++++++++++++++++++++++++++++-------
 1 file changed, 67 insertions(+), 15 deletions(-)
---
diff --git a/rsvg_internals/src/property_macros.rs b/rsvg_internals/src/property_macros.rs
index 41b900e1..eb7f581d 100644
--- a/rsvg_internals/src/property_macros.rs
+++ b/rsvg_internals/src/property_macros.rs
@@ -5,29 +5,80 @@ pub trait Property<T> {
     fn compute(&self, _: &T) -> Self;
 }
 
-/// Generates a property definition that simply parses strings to enum variants
-/// or to a tuple struct of the given type.
+/// Generates a type for a CSS property.
 ///
-/// For example, the SVG spec defines the `stroke-linejoin` property
-/// to have possible values `miter | round | bevel | inherit`, with a default
-/// of `miter`.  We can define the property like this:
+/// Writing a property by hand takes a bit of boilerplate:
+///
+/// * Define a type to represent the property's values.
+///
+/// * A `Parse` implementation to parse the property.
+///
+/// * A `Default` implementation to define the property's *initial* value.
+///
+/// * A `Property` implementation to define whether the property
+/// inherits from the parent element, and how the property calculates
+/// its computed value.
+///
+/// When going from `SpecifiedValues` to `ComputedValues, properties
+/// which inherit automatically from the parent element will just have
+/// their values cloned.  Properties which do not inherit will be reset back
+/// to their initial value (i.e. their `Default`).
+///
+/// The default implementation of `Property::compute()` is to just
+/// clone the property's value.  Properties which need more
+/// sophisticated computation can override this.
+///
+/// This macro allows defining properties of different kinds; see the following
+/// sections for examples.
+///
+/// # Simple identifiers
+///
+/// Many properties are just sets of identifiers and can be represented
+/// by simple enums.  In this case, you can use the following:
 ///
 /// ```ignore
 /// make_property!(
-/// StrokeLinejoin,
-/// default: Miter,
+///   ComputedValues,
+///   StrokeLinejoin,
+///   default: Miter,
+///   inherits_automatically: true,
 ///
-/// "miter" => Miter,
-/// "round" => Round,
-/// "bevel" => Bevel,
+///   identifiers:
+///     "miter" => Miter,
+///     "round" => Round,
+///     "bevel" => Bevel,
 /// );
 /// ```
 ///
-/// The macro will generate a `StrokeLinejoin` enum with the provided
-/// variants.  It will generate an `impl Default for StrokeLinejoin`
-/// with the provided `default:` value.  Finally, it will generate an
-/// `impl Parse for StrokeLinejoin`, from `parsers::Parse`, with
-/// `type Err = ValueErrorKind`.
+/// This generates a simple enum like the following, with implementations of `Parse`,
+/// `Default`, and `Property`.
+///
+/// ```ignore
+/// pub enum StrokeLinejoin { Miter, Round, Bevel }
+/// ```
+///
+/// # Properties from an existing, general-purpose type
+///
+/// For example, both the `lightingColor` and `floodColor` properties can be represented
+/// with a `cssparser::Color`, but their intial values are different.  In this case, the macro
+/// can generate a newtype around `cssparser::Color` for each case:
+///
+/// ```ignore
+/// make_property!(
+///     ComputedValues,
+///     FloodColor,
+///     default: cssparser::Color::RGBA(cssparser::RGBA::new(0, 0, 0, 0)),
+///     inherits_automatically: false,
+///     newtype_parse: cssparser::Color,
+/// );
+/// ```
+///
+/// # Properties from custom specific types
+///
+/// For example, font-related properties have custom, complex types that require an
+/// implentation of `Property::compute` that is more than a simple `clone`.  In this case,
+/// define the custom type separately, and use the macro to specify the default value and
+/// the `Property` implementation.
 #[macro_export]
 macro_rules! make_property {
     ($computed_values_type: ty,
@@ -103,6 +154,7 @@ macro_rules! make_property {
         $parse
     };
 
+    // pending - only XmlLang
     ($computed_values_type: ty,
      $name: ident,
      default: $default: expr,