[glib] GPattern: move docs from tmpl to .c

[Ryan Lortie <ryanl src gnome org>]

commit c7000fcfecca109a9f35c8c2e4e56d3a63cf5bd6
Author: Ryan Lortie <desrt desrt ca>
Date:   Sat Jan 30 23:10:34 2010 -0500

    GPattern: move docs from tmpl to .c

 docs/reference/glib/tmpl/.gitignore    |    1 +
 docs/reference/glib/tmpl/patterns.sgml |  124 --------------------------------
 glib/gpattern.c                        |  103 ++++++++++++++++++++++++++
 3 files changed, 104 insertions(+), 124 deletions(-)
---
diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index dce5b29..fe832de 100644
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -6,6 +6,7 @@ gvarianttype.sgml
 hash_tables.sgml
 memory_chunks.sgml
 option.sgml
+patterns.sgml 
 random_numbers.sgml
 sequence.sgml
 shell.sgml
diff --git a/glib/gpattern.c b/glib/gpattern.c
index 938083e..33e4aac 100644
--- a/glib/gpattern.c
+++ b/glib/gpattern.c
@@ -30,6 +30,38 @@
 #include "gutils.h" 
 #include "galias.h"
 
+/**
+ * SECTION: patterns
+ * @title: Glob-style pattern matching
+ * @short_description: matches strings against patterns containing '*'
+ *                     (wildcard) and '?' (joker)
+ *
+ * The <function>g_pattern_match*</function> functions match a string
+ * against a pattern containing '*' and '?' wildcards with similar
+ * semantics as the standard glob() function: '*' matches an arbitrary,
+ * possibly empty, string, '?' matches an arbitrary character.
+ *
+ * Note that in contrast to glob(), the '/' character
+ * <emphasis>can</emphasis> be matched by the wildcards, there are no
+ * '[...]' character ranges and '*' and '?' can
+ * <emphasis>not</emphasis> be escaped to include them literally in a
+ * pattern.
+ *
+ * When multiple strings must be matched against the same pattern, it
+ * is better to compile the pattern to a #GPatternSpec using
+ * g_pattern_spec_new() and use g_pattern_match_string() instead of
+ * g_pattern_match_simple(). This avoids the overhead of repeated
+ * pattern compilation.
+ **/
+
+/**
+ * GPatternSpec:
+ *
+ * A <structname>GPatternSpec</structname> is the 'compiled' form of a
+ * pattern. This structure is opaque and its fields cannot be accessed
+ * directly.
+ **/
+
 /* keep enum and structure of gpattern.c and patterntest.c in sync */
 typedef enum
 {
@@ -130,6 +162,34 @@ g_pattern_ph_match (const gchar *match_pattern,
   return *string == 0;
 }
 
+/**
+ * g_pattern_match:
+ * @pspec: a #GPatternSpec
+ * @string_length: the length of @string (in bytes, i.e. strlen(),
+ *                 <emphasis>not</emphasis> g_utf8_strlen())
+ * @string: the UTF-8 encoded string to match
+ * @string_reversed: the reverse of @string or %NULL
+ * @Returns: %TRUE if @string matches @pspec
+ *
+ * Matches a string against a compiled pattern. Passing the correct
+ * length of the string given is mandatory. The reversed string can be
+ * omitted by passing %NULL, this is more efficient if the reversed
+ * version of the string to be matched is not at hand, as
+ * g_pattern_match() will only construct it if the compiled pattern
+ * requires reverse matches.
+ *
+ * Note that, if the user code will (possibly) match a string against a
+ * multitude of patterns containing wildcards, chances are high that
+ * some patterns will require a reversed string. In this case, it's
+ * more efficient to provide the reversed string to avoid multiple
+ * constructions thereof in the various calls to g_pattern_match().
+ *
+ * Note also that the reverse of a UTF-8 encoded string can in general
+ * <emphasis>not</emphasis> be obtained by g_strreverse(). This works
+ * only if the string doesn't contain any multibyte characters. GLib
+ * offers the g_utf8_strreverse() function to reverse UTF-8 encoded
+ * strings.
+ **/
 gboolean
 g_pattern_match (GPatternSpec *pspec,
 		 guint         string_length,
@@ -183,6 +243,13 @@ g_pattern_match (GPatternSpec *pspec,
     }
 }
 
+/**
+ * g_pattern_spec_new:
+ * @pattern: a zero-terminated UTF-8 encoded string
+ * @Returns: a newly-allocated #GPatternSpec
+ *
+ * Compiles a pattern to a #GPatternSpec.
+ **/
 GPatternSpec*
 g_pattern_spec_new (const gchar *pattern)
 {
@@ -291,6 +358,12 @@ g_pattern_spec_new (const gchar *pattern)
   return pspec;
 }
 
+/**
+ * g_pattern_spec_free:
+ * @pspec: a #GPatternSpec
+ *
+ * Frees the memory allocated for the #GPatternSpec.
+ **/
 void
 g_pattern_spec_free (GPatternSpec *pspec)
 {
@@ -300,6 +373,15 @@ g_pattern_spec_free (GPatternSpec *pspec)
   g_free (pspec);
 }
 
+/**
+ * g_pattern_spec_equal:
+ * @pspec1: a #GPatternSpec
+ * @pspec2: another #GPatternSpec
+ * @Returns: Whether the compiled patterns are equal
+ *
+ * Compares two compiled pattern specs and returns whether they will
+ * match the same set of strings.
+ **/
 gboolean
 g_pattern_spec_equal (GPatternSpec *pspec1,
 		      GPatternSpec *pspec2)
@@ -312,6 +394,16 @@ g_pattern_spec_equal (GPatternSpec *pspec1,
 	  strcmp (pspec1->pattern, pspec2->pattern) == 0);
 }
 
+/**
+ * g_pattern_match_string:
+ * @pspec: a #GPatternSpec
+ * @string: the UTF-8 encoded string to match
+ * @Returns: %TRUE if @string matches @pspec
+ *
+ * Matches a string against a compiled pattern. If the string is to be
+ * matched against more than one pattern, consider using
+ * g_pattern_match() instead while supplying the reversed string.
+ **/
 gboolean
 g_pattern_match_string (GPatternSpec *pspec,
 			const gchar  *string)
@@ -322,6 +414,17 @@ g_pattern_match_string (GPatternSpec *pspec,
   return g_pattern_match (pspec, strlen (string), string, NULL);
 }
 
+/**
+ * g_pattern_match_simple:
+ * @pattern: the UTF-8 encoded pattern
+ * @string: the UTF-8 encoded string to match
+ * @Returns: %TRUE if @string matches @pspec
+ *
+ * Matches a string against a pattern given as a string. If this
+ * function is to be called in a loop, it's more efficient to compile
+ * the pattern once with g_pattern_spec_new() and call
+ * g_pattern_match_string() repeatedly.
+ **/
 gboolean
 g_pattern_match_simple (const gchar *pattern,
 			const gchar *string)