docs: Tweak bidi docs

Give doc comments summaries, etc.

2 files changed, 22 insertions, 19 deletions

diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index 0fc1c3e4..22335047 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -38,11 +38,11 @@
  * pango_bidi_type_for_unichar:
  * @ch: a Unicode character
  *
- * Determines the normative bidirectional character type of a
- * character, as specified in the Unicode Character Database.
+ * Determines the bidirectional type of a character.
  *
- * A simplified version of this function is available as
- * pango_unichar_direction().
+ * The bidirectional type is specified in the Unicode Character Database.
+ *
+ * A simplified version of this function is available as [func@unichar_direction].
  *
  * Return value: the bidirectional character type, as used in the
  * Unicode bidirectional algorithm.
@@ -96,8 +96,10 @@ pango_bidi_type_for_unichar (gunichar ch)
  *             if @text is nul-terminated and the length should be calculated.
  * @pbase_dir: input base direction, and output resolved direction.
  *
- * This will return the bidirectional embedding levels of the input paragraph
- * as defined by the Unicode Bidirectional Algorithm available at:
+ * Return the bidirectional embedding levels of the input paragraph.
+ *
+ * The bidirectional embedding levels are defined by the Unicode Bidirectional
+ * Algorithm available at:
  *
  *   http://www.unicode.org/reports/tr9/
  *
@@ -105,7 +107,7 @@ pango_bidi_type_for_unichar (gunichar ch)
  * characters in the text will determine the final resolved direction.
  *
  * Return value: a newly allocated array of embedding levels, one item per
- *               character (not byte), that should be freed using g_free.
+ *   character (not byte), that should be freed using g_free().
  *
  * Since: 1.4
  */
@@ -264,14 +266,15 @@ resolved:
  * pango_unichar_direction:
  * @ch: a Unicode character
  *
- * Determines the inherent direction of a character; either
- * %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL, or
- * %PANGO_DIRECTION_NEUTRAL.
+ * Determines the inherent direction of a character.
+ *
+ * The inherent direction is either %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL,
+ * or %PANGO_DIRECTION_NEUTRAL.
  *
  * This function is useful to categorize characters into left-to-right
- * letters, right-to-left letters, and everything else.  If full
- * Unicode bidirectional type of a character is needed,
- * pango_bidi_type_for_unichar() can be used instead.
+ * letters, right-to-left letters, and everything else. If full Unicode
+ * bidirectional type of a character is needed, [func@bidi_type_for_unichar]
+ * can be used instead.
  *
  * Return value: the direction of the character.
  */
@@ -298,9 +301,9 @@ pango_unichar_direction (gunichar ch)
  * @ch: a Unicode character
  * @mirrored_ch: location to store the mirrored character
  *
- * If @ch has the Unicode mirrored property and there is another Unicode
- * character that typically has a glyph that is the mirror image of @ch's
- * glyph, puts that character in the address pointed to by @mirrored_ch.
+ * Returns the mirrored character of a Unicode character.
+ *
+ * Mirror characters are determined by the Unicode mirrored property.
  *
  * Use g_unichar_get_mirror_char() instead; the docs for that function
  * provide full details.
@@ -309,8 +312,8 @@ pango_unichar_direction (gunichar ch)
  * filled in, %FALSE otherwise
  **/
 gboolean
-pango_get_mirror_char (gunichar        ch,
-		       gunichar       *mirrored_ch)
+pango_get_mirror_char (gunichar  ch,
+		       gunichar *mirrored_ch)
 {
   return g_unichar_get_mirror_char (ch, mirrored_ch);
 }
diff --git a/pango/pango-bidi-type.h b/pango/pango-bidi-type.h
index aa1896c1..ebfaa574 100644
--- a/pango/pango-bidi-type.h
+++ b/pango/pango-bidi-type.h
@@ -52,7 +52,7 @@ G_BEGIN_DECLS
  * @PANGO_BIDI_TYPE_WS: Whitespace
  * @PANGO_BIDI_TYPE_ON: Other Neutrals
  *
- * The #PangoBidiType type represents the bidirectional character
+ * `PangoBidiType` represents the bidirectional character
  * type of a Unicode character as specified by the
  * <ulink url="http://www.unicode.org/reports/tr9/">Unicode bidirectional algorithm</ulink>.
  *