Update doc comments. Mention that it is not recommeded to use the Registry

2007-06-11  Tor Lillqvist  <tml@novell.com>

	* glib/gwin32.c (g_win32_get_package_installation_directory)
	(g_win32_get_package_installation_subdirectory): Update doc
	comments. Mention that it is not recommeded to use the Registry
	features.

svn path=/trunk/; revision=5547

diff --git a/ChangeLog b/ChangeLog
index 89a9a89..721bef6 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2007-06-11  Tor Lillqvist  <tml@novell.com>
+
+       * glib/gwin32.c (g_win32_get_package_installation_directory)
+       (g_win32_get_package_installation_subdirectory): Update doc
+       comments. Mention that it is not recommeded to use the Registry
+       features.
+
 2007-06-06  Tor Lillqvist  <tml@novell.com>
 
        * glib/gutils.c: Add definitions for more CSIDL_* constants in

diff --git a/glib/gwin32.c b/glib/gwin32.c
index f7de19f..b97383b 100644 (file)
--- a/glib/gwin32.c
+++ b/glib/gwin32.c
@@ -274,16 +274,26 @@ get_package_directory_from_module (const gchar *module_name)
  * @dll_name: The name of a DLL that a package provides, or %NULL, in UTF-8
  *
  * Try to determine the installation directory for a software package.
- * Typically used by GNU software packages.
  *
  * @package should be a short identifier for the package. Typically it
  * is the same identifier as used for
- * <literal>GETTEXT_PACKAGE</literal> in software configured according
- * to GNU standards. The function first looks in the Windows Registry
- * for the value <literal>&num;InstallationDirectory</literal> in the key
+ * <literal>GETTEXT_PACKAGE</literal> in software configured using GNU
+ * autotools. The function first looks in the Windows Registry for the
+ * value <literal>&num;InstallationDirectory</literal> in the key
  * <literal>&num;HKLM\Software\@package</literal>, and if that value
  * exists and is a string, returns that.
  *
+ * It is strongly recommended that packagers of GLib-using libraries
+ * for Windows do not store installation paths in the Registry to be
+ * used by this function as that interfers with having several
+ * parallel installations of the library. Parallel installations of
+ * different versions of some GLib-using library, or GLib itself,
+ * might well be desirable for various reasons.
+ *
+ * For the same reason it is recommeded to always pass %NULL as
+ * @package to this function, to avoid the temptation to use the
+ * Registry.
+ *
  * If @package is %NULL, or the above value isn't found in the
  * Registry, but @dll_name is non-%NULL, it should name a DLL loaded
  * into the current process. Typically that would be the name of the
@@ -419,7 +429,10 @@ g_win32_get_package_installation_directory (const gchar *package,
  * Returns a newly-allocated string containing the path of the
  * subdirectory @subdir in the return value from calling
  * g_win32_get_package_installation_directory() with the @package and
- * @dll_name parameters. 
+ * @dll_name parameters. See the documentation for
+ * g_win32_get_package_installation_directory() for more details. In
+ * particular, note that it is recomended to always pass NULL as
+ * @package.
  *
  * Returns: a string containing the complete path to @subdir inside
  * the installation directory of @package. The returned string is in