Added class documentation.

2008-01-11  Murray Cumming  <murrayc@murrayc.com>

* gio/src/appinfo.hg: Added class documentation.
* gio/src/asyncresult.hg:
* gio/src/cancellable.hg:
* gio/src/drive.hg:
* gio/src/file.hg:
* gio/src/fileattribute.hg:
* gio/src/fileenumerator.hg:
* gio/src/fileicon.hg:
* gio/src/fileinfo.hg:
* gio/src/fileinputstream.hg:
* gio/src/fileoutputstream.hg:
* gio/src/icon.hg:
* gio/src/inputstream.hg:
* gio/src/loadableicon.hg:
* gio/src/mountoperation.hg:
* gio/src/outputstream.hg:
* gio/src/seekable.hg:
* gio/src/simpleasyncresult.hg:
* gio/src/volume.hg: Added @newin2p16 to 
the documentation.

* glib/src/Makefile_list_of_hg.am_fragment:
* glib/src/uriutils.ccg:
* glib/src/uriutils.hg: Added wrappers of (some) of 
these new g_uri_* functions. Not yet documented.

svn path=/trunk/; revision=506

25 files changed, 200 insertions, 9 deletions

diff --git a/ChangeLog b/ChangeLog
index 5f44a982..81c19ffd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,33 @@
 2008-01-11  Murray Cumming  <murrayc@murrayc.com>
 
+	* gio/src/appinfo.hg: Added class documentation.
+	* gio/src/asyncresult.hg:
+	* gio/src/cancellable.hg:
+	* gio/src/drive.hg:
+	* gio/src/file.hg:
+	* gio/src/fileattribute.hg:
+	* gio/src/fileenumerator.hg:
+	* gio/src/fileicon.hg:
+	* gio/src/fileinfo.hg:
+	* gio/src/fileinputstream.hg:
+	* gio/src/fileoutputstream.hg:
+	* gio/src/icon.hg:
+	* gio/src/inputstream.hg:
+	* gio/src/loadableicon.hg:
+	* gio/src/mountoperation.hg:
+	* gio/src/outputstream.hg:
+	* gio/src/seekable.hg:
+	* gio/src/simpleasyncresult.hg:
+	* gio/src/volume.hg: Added @newin2p16 to 
+	the documentation.
+
+	* glib/src/Makefile_list_of_hg.am_fragment:
+	* glib/src/uriutils.ccg:
+	* glib/src/uriutils.hg: Added wrappers of (some) of 
+	these new g_uri_* functions. Not yet documented.
+
+2008-01-11  Murray Cumming  <murrayc@murrayc.com>
+
 	* gio/src/file.ccg:
 	* gio/src/file.hg: Rename create() to create_file(), 
 	create_async() to create_file_async() and 
diff --git a/docs/reference/Doxyfile.in b/docs/reference/Doxyfile.in
index 9ef4bb82..75d19cd1 100644
--- a/docs/reference/Doxyfile.in
+++ b/docs/reference/Doxyfile.in
@@ -155,6 +155,8 @@ ALIASES                += "newin2p10=\xrefitem newin2p10s \"Since glibmm 2.10\"
 ALIASES                += "newin2p12=\xrefitem newin2p12s \"Since glibmm 2.12\" \"New API since glibmm 2.12\""
 ALIASES                += "newin2p14=\xrefitem newin2p14s \"Since glibmm 2.14\" \"New API since glibmm 2.14\""
 ALIASES                += "newin2p16=\xrefitem newin2p16s \"Since glibmm 2.16\" \"New API since glibmm 2.16\""
+ALIASES                += "newin2p18=\xrefitem newin2p18s \"Since glibmm 2.18\" \"New API since glibmm 2.18\""
+ALIASES                += "newin2p20=\xrefitem newin2p20s \"Since glibmm 2.20\" \"New API since glibmm 2.20\""
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources 
 # only. Doxygen will then generate output that is more tailored for C. 
diff --git a/gio/src/appinfo.hg b/gio/src/appinfo.hg
index 62275125..a7dccea9 100644
--- a/gio/src/appinfo.hg
+++ b/gio/src/appinfo.hg
@@ -39,6 +39,11 @@ _WRAP_ENUM(AppInfoCreateFlags, GAppInfoCreateFlags, NO_GTYPE)
 
 class AppInfo;
 
+/** This is used to handle, for instance, startup notification and launching of the new application on the same screen as the launching window.
+ * See also AppInfo.
+ *
+ * @newin2p16
+ */
 class AppLaunchContext : public Glib::Object
 {
   _CLASS_GOBJECT(AppLaunchContext, GAppLaunchContext, G_APP_LAUNCH_CONTEXT, Glib::Object, GObject)
@@ -49,16 +54,20 @@ protected:
 public:
   _WRAP_CREATE()
 
-  _WRAP_METHOD(std::string get_display(const Glib::RefPtr<AppInfo>& info,
-                                       const Glib::ListHandle<std::string>& files),
+  _WRAP_METHOD(std::string get_display(const Glib::RefPtr<AppInfo>& info, const Glib::ListHandle<std::string>& files),
                g_app_launch_context_get_display)
-  _WRAP_METHOD(std::string get_startup_notify_id(const Glib::RefPtr<AppInfo>& info,
-                                                 const Glib::ListHandle<std::string>& files),
+  _WRAP_METHOD(std::string get_startup_notify_id(const Glib::RefPtr<AppInfo>& info, const Glib::ListHandle<std::string>& files),
                g_app_launch_context_get_startup_notify_id)
   _WRAP_METHOD(void launch_failed(const std::string& startup_notify_id),
                g_app_launch_context_launch_failed)
 };
 
+/** Application information, to describe applications installed on the system, 
+ * and launch them.
+ * See also AppLaunchContext.
+ *
+ * @newin2p16
+ */
 class AppInfo : public Glib::Interface
 {
   _CLASS_INTERFACE(AppInfo, GAppInfo, G_APP_INFO, GAppInfoIface)
@@ -78,6 +87,8 @@ public:
   _IGNORE(g_app_info_dup)
   _IGNORE(g_app_info_equal)
 
+  // TODO: Decide whether this is a good idea. murrayc
+  // TODO: Documentation.
   // I declare this as virtual so that it is possible to override
   // the method in possible derived classes. markoa
   virtual bool equal(const Glib::RefPtr<AppInfo>& other) const;
@@ -122,14 +133,15 @@ public:
 
   static Glib::ListHandle< Glib::RefPtr<AppInfo> > get_all_for_type(const std::string& content_type);
 
-  static Glib::RefPtr<AppInfo> get_default_for_type(const std::string& content_type,
-                                                    bool must_support_uris = true);
+  static Glib::RefPtr<AppInfo> get_default_for_type(const std::string& content_type, bool must_support_uris = true);
 
   static Glib::RefPtr<AppInfo> get_default_for_uri_scheme(const std::string& uri_scheme);
 
   //TODO: vfuncs?
 };
 
+//TODO: Probably remove these (and others elsewhere) because they will lead to confusion with the regular RefPtr operator==. murrayc.
+
 /** @relates Gio::AppInfo */
 inline bool operator==(const Glib::RefPtr<AppInfo>& lhs, const Glib::RefPtr<AppInfo>& rhs)
 { return lhs->equal(rhs); }
@@ -139,3 +151,4 @@ inline bool operator!=(const Glib::RefPtr<AppInfo>& lhs, const Glib::RefPtr<AppI
 { return ! lhs->equal(rhs); }
 
 } // namespace Gio
+
diff --git a/gio/src/asyncresult.hg b/gio/src/asyncresult.hg
index 396cdbf6..65e5d41c 100644
--- a/gio/src/asyncresult.hg
+++ b/gio/src/asyncresult.hg
@@ -39,6 +39,8 @@ class AsyncResult;
  * @code
  * void on_async_ready(Glib::RefPtr<AsyncResult>& result);
  * @endcode
+ *
+ * @newin2p16
  */
 typedef sigc::slot<void, Glib::RefPtr<AsyncResult>& > SlotAsyncReady;
 
@@ -96,6 +98,8 @@ typedef sigc::slot<void, Glib::RefPtr<AsyncResult>& > SlotAsyncReady;
  *
  * Some ascynchronous operations are implemented using synchronous calls. These are run in a separate GThread, but otherwise they are sent 
  * to the Main Event Loop and processed in an idle function. So, if you truly need asynchronous operations, make sure to initialize GThread.
+ *
+ * @newin2p16
  */
 class AsyncResult : public Glib::Interface
 {
diff --git a/gio/src/cancellable.hg b/gio/src/cancellable.hg
index fd6bcd0f..e0b04407 100644
--- a/gio/src/cancellable.hg
+++ b/gio/src/cancellable.hg
@@ -30,6 +30,8 @@ namespace Gio
 
 /** Allows actions to be cancelled.
  * Cancellable is a thread-safe operation cancellation stack used throughout GIO to allow for cancellation of synchronous and asynchronous operations.
+ *
+ * @newin2p16
  */
 class Cancellable : public Glib::Object
 {
diff --git a/gio/src/drive.hg b/gio/src/drive.hg
index 2ccc84d6..cc4ed5cf 100644
--- a/gio/src/drive.hg
+++ b/gio/src/drive.hg
@@ -40,6 +40,8 @@ namespace Gio
  *
  * If the Gio::Drive reports that media isn't automatically detected, one can poll for media; typically one should not do this periodically as a 
  * poll for media operation is potententially expensive and may spin up the drive, creating noise.
+ *
+ * @newin2p16
  */
 class Drive : public Glib::Interface
 {
diff --git a/gio/src/file.hg b/gio/src/file.hg
index cd0b75b9..4c29cad4 100644
--- a/gio/src/file.hg
+++ b/gio/src/file.hg
@@ -62,6 +62,8 @@ _WRAP_ENUM(FileMonitorFlags, GFileMonitorFlags, NO_GTYPE)
  * One notable feature of Gio::Files are entity tags, or "etags" for short. Entity tags are somewhat like a more abstract version of the 
  * traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. 
  * See the HTTP 1.1 specification for HTTP Etag headers, which are a very similar concept.
+ *
+ * @newin2p16
  */ 
 class File : public Glib::Interface
 {
diff --git a/gio/src/fileattribute.hg b/gio/src/fileattribute.hg
index 3ca25617..e58f4076 100644
--- a/gio/src/fileattribute.hg
+++ b/gio/src/fileattribute.hg
@@ -35,6 +35,8 @@ _WRAP_ENUM(FileAttributeStatus, GFileAttributeStatus, NO_GTYPE)
 // TODO: Use _CLASS_GENERIC?
 
 /** Information about a specific attribute - see FileAttributeInfoList.
+ *
+ * @newin2p16
  */
 class FileAttributeInfo
 {
@@ -75,6 +77,8 @@ protected:
  * the user id for a given file).
  *
  * See http://library.gnome.org/devel/gio/unstable/gio-GFileAttribute.html for the list of default namespaces and the list of default keys.
+ *
+ * @newin2p16
  */
 class FileAttributeInfoList
 {
diff --git a/gio/src/fileenumerator.hg b/gio/src/fileenumerator.hg
index fa3b12fd..003e4aa9 100644
--- a/gio/src/fileenumerator.hg
+++ b/gio/src/fileenumerator.hg
@@ -44,6 +44,8 @@ namespace Gio
  *
  * To close a Gio::FileEnumerator, use FileEnumerator::close(), or its asynchronous version, close_async(). Once a FileEnumerator is closed, 
  * no further actions may be performed on it.
+ *
+ * @newin2p16
  */
 class FileEnumerator : public Glib::Object
 {
diff --git a/gio/src/fileicon.hg b/gio/src/fileicon.hg
index 739d01bb..dd151389 100644
--- a/gio/src/fileicon.hg
+++ b/gio/src/fileicon.hg
@@ -31,6 +31,8 @@ namespace Gio
 {
 
 /** FileIcon specifies an icon by pointing to an image file to be used as icon.
+ *
+ * @newin2p16
  */
 class FileIcon
 : public Glib::Object,
diff --git a/gio/src/fileinfo.hg b/gio/src/fileinfo.hg
index 9b6f8cfd..5d4debf7 100644
--- a/gio/src/fileinfo.hg
+++ b/gio/src/fileinfo.hg
@@ -36,6 +36,8 @@ _WRAP_ENUM(FileType, GFileType, NO_GTYPE)
 //TODO: attribute strings
 
 /** FileAttributeMatcher allows for searching through a FileInfo for attributes.
+ *
+ * @newin2p16
  */
 class FileAttributeMatcher
 {
diff --git a/gio/src/fileinputstream.hg b/gio/src/fileinputstream.hg
index 335edfe4..0ee1d073 100644
--- a/gio/src/fileinputstream.hg
+++ b/gio/src/fileinputstream.hg
@@ -39,6 +39,8 @@ namespace Gio
  * provided the filesystem of the file allows it. In addition to the generic Seekable API, FileInputStream has its own API 
  * for seeking and positioning. To find the position of a file input stream, use tell(). To find out if a file input stream supports 
  * seeking, use can_seek(). To position a file input stream, use seek().
+ *
+ * @newin2p16
  */
 class FileInputStream 
 : public Gio::InputStream, 
diff --git a/gio/src/fileoutputstream.hg b/gio/src/fileoutputstream.hg
index fba1a9a9..557567de 100644
--- a/gio/src/fileoutputstream.hg
+++ b/gio/src/fileoutputstream.hg
@@ -43,6 +43,8 @@ namespace Gio
  * file output stream, use seek(). To find out if a file output stream supports 
  * truncating, use can_truncate(). To truncate a file output stream, use 
  * truncate().
+ *
+ * @newin2p16
  */
 class FileOutputStream
 : public OutputStream,
diff --git a/gio/src/icon.hg b/gio/src/icon.hg
index c3a504ef..18ce4fcb 100644
--- a/gio/src/icon.hg
+++ b/gio/src/icon.hg
@@ -34,6 +34,8 @@ namespace Gio
  * To obtain a hash of an Icon instance, see hash().
  *
  * To check if two Icon instances are equal, see equal().
+ *
+ * @newin2p16
  */
 class Icon : public Glib::Interface
 {
diff --git a/gio/src/inputstream.hg b/gio/src/inputstream.hg
index af19f17f..b1daa6b3 100644
--- a/gio/src/inputstream.hg
+++ b/gio/src/inputstream.hg
@@ -31,6 +31,8 @@ namespace Gio
 {
 
 /** Base class for implementing streaming input.
+ *
+ * @newin2p16
  */
 class InputStream : public Glib::Object
 {
diff --git a/gio/src/loadableicon.hg b/gio/src/loadableicon.hg
index 637ff212..02f40cb6 100644
--- a/gio/src/loadableicon.hg
+++ b/gio/src/loadableicon.hg
@@ -30,6 +30,8 @@ namespace Gio
 //TODO: Derive from Icon?
 
 /** Extends the Icon interface and adds the ability to load icons from streams.
+ *
+ * @newin2p16
  */
 class LoadableIcon : public Glib::Interface
 {
diff --git a/gio/src/mountoperation.hg b/gio/src/mountoperation.hg
index 2a109b0e..b381fa9d 100644
--- a/gio/src/mountoperation.hg
+++ b/gio/src/mountoperation.hg
@@ -40,6 +40,8 @@ _WRAP_ENUM(MountOperationResult, GMountOperationResult, NO_GTYPE)
  * WebDAV.
  *
  * Developers should instantiate a subclass of this that implements all the various callbacks to show the required dialogs.
+ *
+ * @newin2p16
  */
 class MountOperation : public Glib::Object
 {
diff --git a/gio/src/outputstream.hg b/gio/src/outputstream.hg
index 5b41c7bf..fad8ba8a 100644
--- a/gio/src/outputstream.hg
+++ b/gio/src/outputstream.hg
@@ -33,6 +33,8 @@ namespace Gio
 _WRAP_ENUM(OutputStreamSpliceFlags, GOutputStreamSpliceFlags, NO_GTYPE)
 
 /** Base class for implementing streaming output.
+ *
+ * @newin2p16
  */
 class OutputStream : public Glib::Object
 {
diff --git a/gio/src/seekable.hg b/gio/src/seekable.hg
index e498e4f3..dfd27193 100644
--- a/gio/src/seekable.hg
+++ b/gio/src/seekable.hg
@@ -29,6 +29,8 @@ namespace Gio
 
 /** Stream seeking interface.
  * Seekable is implemented by streams (implementations of InputStream or OutputStream) that support seeking.
+ *
+ * @newin2p16
  */
 class Seekable : public Glib::Interface
 {
diff --git a/gio/src/simpleasyncresult.hg b/gio/src/simpleasyncresult.hg
index 776f1568..925660f2 100644
--- a/gio/src/simpleasyncresult.hg
+++ b/gio/src/simpleasyncresult.hg
@@ -60,6 +60,8 @@ namespace Gio
  * 
  * Likewise, to get the result of an asynchronous function, get_op_res_gpointer(), get_op_res_bool(), and 
  * get_op_res_gssize() are provided, getting the operation's result as a gpointer, bool, and gssize, respectively.
+ *
+ * @newin2p16
  */
 class SimpleAsyncResult : public Glib::Object, public AsyncResult
 {
diff --git a/gio/src/volume.hg b/gio/src/volume.hg
index 23e148bf..0953b494 100644
--- a/gio/src/volume.hg
+++ b/gio/src/volume.hg
@@ -47,6 +47,8 @@ class File;
  * The callback will be fired when the operation has resolved (either with success or failure), and a AsyncReady structure will be passed to the callback. 
  * That callback should then call g_volume_mount_finish() with the GVolume instance and the GAsyncReady data to see if the operation was completed 
  * successfully. If an error is present when finish() is called, then it will be filled with any error information.
+ *
+ * @newin2p16
  */
 class Volume : public Glib::Interface
 {
diff --git a/glib/src/Makefile_list_of_hg.am_fragment b/glib/src/Makefile_list_of_hg.am_fragment
index 2be07cf0..c12b5591 100644
--- a/glib/src/Makefile_list_of_hg.am_fragment
+++ b/glib/src/Makefile_list_of_hg.am_fragment
@@ -5,6 +5,8 @@
 
 files_posix_hg =
 files_win32_hg =
-files_general_hg = convert.hg date.hg fileutils.hg iochannel.hg keyfile.hg markup.hg module.hg optioncontext.hg optionentry.hg optiongroup.hg regex.hg shell.hg spawn.hg thread.hg unicode.hg
+files_general_hg = convert.hg date.hg fileutils.hg iochannel.hg keyfile.hg markup.hg \
+                   module.hg optioncontext.hg optionentry.hg optiongroup.hg regex.hg \
+                   shell.hg spawn.hg thread.hg unicode.hg uriutils.hg 
 
 include $(top_srcdir)/build_shared/Makefile_build_gensrc.am_fragment 
diff --git a/glib/src/fileutils.ccg b/glib/src/fileutils.ccg
index 144c48b5..5df5e5de 100644
--- a/glib/src/fileutils.ccg
+++ b/glib/src/fileutils.ccg
@@ -1,5 +1,5 @@
 // -*- c++ -*-
-/* $Id$ */
+/* $Id: fileutils.ccg,v 1.1 2003/01/07 16:58:25 murrayc Exp $ */
 
 /* Copyright (C) 2002 The gtkmm Development Team
  *
@@ -52,7 +52,7 @@ Dir::~Dir()
 std::string Dir::read_name()
 {
   const char *const name = g_dir_read_name(gobject_);
-  return (name) ? std::string(name) : std::string();
+  return Glib::convert_const_gchar_ptr_to_stdstring(name);
 }
 
 void Dir::rewind()
diff --git a/glib/src/uriutils.ccg b/glib/src/uriutils.ccg
new file mode 100644
index 00000000..99ff68a1
--- /dev/null
+++ b/glib/src/uriutils.ccg
@@ -0,0 +1,45 @@
+// -*- c++ -*-
+/* $Id: fileutils.ccg,v 1.1 2003/01/07 16:58:25 murrayc Exp $ */
+
+/* Copyright (C) 2002 The gtkmm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the Free
+ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <glib/gurifuncs.h>
+#include <glibmm/utility.h>
+
+namespace Glib
+{
+
+std::string uri_unescape_string(const std::string& escaped_string, const std::string& illegal_characters)
+{
+  const gchar* cresult = g_uri_unescape_string(escaped_string.c_str(), illegal_characters.c_str());
+  return Glib::convert_const_gchar_ptr_to_stdstring(cresult);
+}
+
+std::string uri_get_scheme(const std::string& uri)
+{
+  return Glib::convert_const_gchar_ptr_to_stdstring( g_uri_get_scheme(uri.c_str()) );
+}
+
+std::string uri_escape_string(const std::string& unescaped, const std::string& reserved_chars_allowed, bool allow_utf8)
+{
+  const gchar* cresult = g_uri_escape_string(unescaped.c_str(), reserved_chars_allowed.c_str(), allow_utf8);
+  return Glib::convert_const_gchar_ptr_to_stdstring(cresult);
+}
+
+} // namespace Glib
+
diff --git a/glib/src/uriutils.hg b/glib/src/uriutils.hg
new file mode 100644
index 00000000..5a17b4cd
--- /dev/null
+++ b/glib/src/uriutils.hg
@@ -0,0 +1,61 @@
+/* $Id: fileutils.hg,v 1.3 2004/01/22 18:38:12 murrayc Exp $ */
+
+/* Copyright (C) 2002 The gtkmm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the Free
+ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+_DEFS(glibmm,glib)
+
+#include <string>
+
+#include <glibmmconfig.h>
+
+GLIBMM_USING_STD(string)
+
+namespace Glib
+{
+
+/** @defgroup UriUtils URI Utilities
+ * Various uri-related functions.
+ */
+
+//TODO: Documentation: See http://bugzilla.gnome.org/show_bug.cgi?id=508773
+
+/**
+ * @ingroup UriUtils
+ * @newin2p16
+ */
+std::string uri_unescape_string(const std::string& escaped_string, const std::string& illegal_characters);
+
+//TODO: Use iterator? 
+//char *   g_uri_unescape_segment      (const char *escaped_string,
+//				      const char *escaped_string_end,
+//				      const char *illegal_characters);
+
+/**
+ * @ingroup UriUtils
+ * @newin2p16
+ */
+std::string uri_get_scheme(const std::string& uri);
+
+/**
+ * @ingroup UriUtils
+ * @newin2p16
+ */
+std::string uri_escape_string(const std::string& unescaped, const std::string& reserved_chars_allowed, bool allow_utf8 = true);
+
+} // namespace Glib
+