docs: Tweak color docs

Give doc comments summaries, etc.

1 files changed, 21 insertions, 14 deletions

diff --git a/pango/pango-color.c b/pango/pango-color.c
index 7f939030..f616e1f0 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -36,14 +36,15 @@ G_DEFINE_BOXED_TYPE (PangoColor, pango_color,
  * pango_color_copy:
  * @src: (nullable): color to copy, may be %NULL
  *
- * Creates a copy of @src, which should be freed with
- * pango_color_free(). Primarily used by language bindings,
- * not that useful otherwise (since colors can just be copied
- * by assignment in C).
+ * Creates a copy of @src.
  *
- * Return value: (nullable): the newly allocated #PangoColor, which
- *               should be freed with pango_color_free(), or %NULL if
- *               @src was %NULL.
+ * The copy should be freed with pango_color_free(). Primarily
+ * used by language bindings, not that useful otherwise (since
+ * colors can just be copied by assignment in C).
+ *
+ * Return value: (nullable): the newly allocated `PangoColor`, which
+ *   should be freed with [method@Pango.Color.free], or %NULL if
+ *   @src was %NULL.
  **/
 PangoColor*
 pango_color_copy (const PangoColor *src)
@@ -79,9 +80,11 @@ pango_color_free (PangoColor *color)
  * pango_color_to_string:
  * @color: a #PangoColor
  *
- * Returns a textual specification of @color in the hexadecimal form
- * `#rrrrggggbbbb`, where `r`, `g` and `b` are hex digits representing
- * the red, green, and blue components respectively.
+ * Returns a textual specification of @color.
+ *
+ * The string is in the hexadecimal form `#rrrrggggbbbb`, where
+ * `r`, `g` and `b` are hex digits representing the red, green,
+ * and blue components respectively.
  *
  * Return value: a newly-allocated text string that must be freed with g_free().
  *
@@ -208,12 +211,14 @@ hex (const char *spec,
 
 /**
  * pango_color_parse_with_alpha:
- * @color: (nullable): a #PangoColor structure in which to store the
+ * @color: (nullable): a `PangoColor` structure in which to store the
  *   result, or %NULL
  * @alpha: (out) (optional): return location for alpha, or %NULL
  * @spec: a string specifying the new color
  *
- * Fill in the fields of a color from a string specification. The string can
+ * Fill in the fields of a color from a string specification.
+ *
+ * The string can
  * either one of a large set of standard names. (Taken from the CSS Color
  * [specification](https://www.w3.org/TR/css-color-4/#named-colors),
  * or it can be a hexadecimal value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb`
@@ -315,11 +320,13 @@ pango_color_parse_with_alpha (PangoColor *color,
 
 /**
  * pango_color_parse:
- * @color: (nullable): a #PangoColor structure in which to store the
+ * @color: (nullable): a `PangoColor` structure in which to store the
  *   result, or %NULL
  * @spec: a string specifying the new color
  *
- * Fill in the fields of a color from a string specification. The string can either
+ * Fill in the fields of a color from a string specification.
+ *
+ * The string can either
  * one of a large set of standard names. (Taken from the CSS Color
  * [specification](https://www.w3.org/TR/css-color-4/#named-colors), or it can be
  * a value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb`, where