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)

diff --git a/ChangeLog b/ChangeLog
index 7a97140c2155a3fa84eb11d623d790053bd945fc..b26f4e42b7c32644d1fa1af291682af4eef6becb 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+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)
+
 2003-10-28  Padraig O'Briain  <padraig.obriain@sun.com>
 
        * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_remove_filter):

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 7a97140c2155a3fa84eb11d623d790053bd945fc..b26f4e42b7c32644d1fa1af291682af4eef6becb 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,9 @@
+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)
+
 2003-10-28  Padraig O'Briain  <padraig.obriain@sun.com>
 
        * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_remove_filter):

diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index 7a97140c2155a3fa84eb11d623d790053bd945fc..b26f4e42b7c32644d1fa1af291682af4eef6becb 100644 (file)
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,3 +1,9 @@
+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)
+
 2003-10-28  Padraig O'Briain  <padraig.obriain@sun.com>
 
        * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_remove_filter):

diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 7a97140c2155a3fa84eb11d623d790053bd945fc..b26f4e42b7c32644d1fa1af291682af4eef6becb 100644 (file)
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,9 @@
+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)
+
 2003-10-28  Padraig O'Briain  <padraig.obriain@sun.com>
 
        * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_remove_filter):

diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 7a97140c2155a3fa84eb11d623d790053bd945fc..b26f4e42b7c32644d1fa1af291682af4eef6becb 100644 (file)
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,9 @@
+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)
+
 2003-10-28  Padraig O'Briain  <padraig.obriain@sun.com>
 
        * gtk/gtkfilechooserdefault.c (gtk_file_chooser_default_remove_filter):

diff --git a/docs/reference/gtk/tmpl/gtkfeatures.sgml b/docs/reference/gtk/tmpl/gtkfeatures.sgml
index 3f0bcabe920f8988d306a23707b5b13aec1b53b7..634dfafa6462d4c0fd6e52d1d9fbe2c76512d912 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkfeatures.sgml
+++ b/docs/reference/gtk/tmpl/gtkfeatures.sgml
@@ -76,21 +76,12 @@ about it. ;-)
 
 <!-- ##### FUNCTION gtk_check_version ##### -->
 <para>
-Checks that the GTK+ library in use is equal to the given 
-version. Primarily useful to compare the header file version 
-(from #GTK_MAJOR_VERSION, #GTK_MINOR_VERSION, #GTK_MICRO_VERSION) 
-the the runtime library version. This should only be done 
-in the build for your application, to check that the user's libraries
-and header files are the same. Applications should not do this 
-when deployed, because it's OK for applications to use a different
-micro version of GTK+ than the one they were compiled against.
-</para>
-
-@required_major: the required major version.
-@required_minor: the required major version.
-@required_micro: the required major version.
-@Returns: %NULL if the GTK+ library is compatible with the given version, or
-a string describing the version mismatch.
+</para>
+
+@required_major: 
+@required_minor:
+@required_micro:
+@Returns:
 
 
 <!-- ##### MACRO GTK_MAJOR_VERSION ##### -->

diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 38b9fadb1cd6df159420bdea7a37369e6a61884b..8681457452425100757c459464a35d60aafff3bc 100644 (file)
--- 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,