Move docs inline, rewrite docs, mention memory management for the return

Tue Oct 28 09:21:29 2003  Owen Taylor  <otaylor@redhat.com>

        * gtk/gtkmain.c (gtk_check_version): Move docs inline,
        rewrite docs, mention memory management for the return
        value. (Partly addresses #125549, Michael Natterer)

1 files changed, 34 insertions, 0 deletions

diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 38b9fadb1..868145745 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -172,6 +172,40 @@ static const guint gtk_ndebug_keys = sizeof (gtk_debug_keys) / sizeof (GDebugKey
 
 #endif /* G_ENABLE_DEBUG */
 
+/**
+ * gtk_check_version:
+ * @required_major: the required major version.
+ * @required_minor: the required major version.
+ * @required_micro: the required major version.
+ * 
+ * Checks that the GTK+ library in use is compatible with the
+ * given version. Generally you would pass in the constants
+ * #GTK_MAJOR_VERSION, #GTK_MINOR_VERSION, #GTK_MICRO_VERSION
+ * as the three arguments to this function; that produces
+ * a check that the library in use is compatible with
+ * the version of GTK+ the application or module was compiled
+ * against.
+ *
+ * Compatibility is defined by two things: first the version
+ * of the running library is newer than the version
+ * @required_major.required_minor.@required_micro. Second
+ * the running library must be binary compatible with the
+ * version @required_major.required_minor.@required_micro
+ * (same major version.)
+ *
+ * This function is primarily for GTK+ modules; the module
+ * can call this function to check that it wasn't loaded
+ * into an incompatible version of GTK+. However, such a
+ * a check isn't completely reliable, since the module may be
+ * linked against an old version of GTK+ and calling the
+ * old version of gtk_check_version(), but still get loaded
+ * into an application using a newer version of GTK+.
+ *
+ * Return value: %NULL if the GTK+ library is compatible with the
+ *   given version, or a string describing the version mismatch.
+ *   The returned string is owned by GTK+ and should not be modified
+ *   or freed.
+ **/
 gchar*
 gtk_check_version (guint required_major,
 		   guint required_minor,