[glibmm] Dealt with several TODOs.
- From: Murray Cumming <murrayc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glibmm] Dealt with several TODOs.
- Date: Tue, 15 Feb 2011 11:30:49 +0000 (UTC)
commit efa5be64159016d2b9cc4ac8d1cc5a6176703ce7
Author: Murray Cumming <murrayc murrayc com>
Date: Tue Feb 15 12:30:41 2011 +0100
Dealt with several TODOs.
* gio/src/*.[hg|ccg]: Mostly just adding hand-coded documentation,
and changing some new methods to use std::vector.
ChangeLog | 7 +++
gio/src/actiongroup.hg | 5 +-
gio/src/application.ccg | 31 +++----------
gio/src/application.hg | 1 +
gio/src/applicationcommandline.hg | 14 +++++-
gio/src/bufferedinputstream.hg | 12 +++++-
gio/src/bufferedoutputstream.hg | 12 +++++-
gio/src/datainputstream.hg | 4 +-
gio/src/dbusmessage.hg | 6 +-
gio/src/dbusserver.hg | 2 +-
gio/src/desktopappinfo.hg | 2 +-
gio/src/emblem.hg | 17 +++++++-
gio/src/emblemedicon.ccg | 6 +++
gio/src/emblemedicon.hg | 29 ++++++++++++-
gio/src/file.hg | 48 +++++++++++++++++++-
gio/src/filterinputstream.hg | 4 +-
gio/src/filteroutputstream.hg | 5 +-
gio/src/memoryoutputstream.hg | 4 +-
gio/src/proxy.hg | 6 ++-
gio/src/proxyresolver.ccg | 5 +-
gio/src/proxyresolver.hg | 30 ++++++++++---
gio/src/resolver.hg | 86 ++++++++++++++++++++++++++++++++---
gio/src/seekable.hg | 4 +-
gio/src/settings.hg | 11 +++--
gio/src/socket.hg | 4 +-
gio/src/socketaddressenumerator.hg | 27 ++++++++++-
gio/src/socketclient.hg | 72 +++++++++++++++++++++++++-----
gio/src/socketcontrolmessage.hg | 2 +-
gio/src/themedicon.hg | 13 +++++-
glib/src/optioncontext.hg | 9 +++-
glib/src/varianttype.hg | 6 ++-
31 files changed, 391 insertions(+), 93 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 4f146ec..e2243ae 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
2011-02-15 Murray Cumming <murrayc murrayc com>
+ Dealt with several TODOs.
+
+ * gio/src/*.[hg|ccg]: Mostly just adding hand-coded documentation,
+ and changing some new methods to use std::vector.
+
+2011-02-15 Murray Cumming <murrayc murrayc com>
+
Update the .defs for signals and properties.
* tools/extra_defs_gen/generate_defs_gio.cc: Mention more GDbus types.
diff --git a/gio/src/actiongroup.hg b/gio/src/actiongroup.hg
index 3375628..8ff29e9 100644
--- a/gio/src/actiongroup.hg
+++ b/gio/src/actiongroup.hg
@@ -53,9 +53,8 @@ class ActionGroup : public Glib::Interface
public:
_WRAP_METHOD(bool has_action(const Glib::ustring& action_name) const, g_action_group_has_action)
- //TODO: Use a vector instead, for this new API, before we free glibmm 2.28.
-#m4 _CONVERSION(`gchar**', `Glib::StringArrayHandle', `Glib::StringArrayHandle($3, Glib::OWNERSHIP_DEEP)')
- _WRAP_METHOD(Glib::StringArrayHandle list_actions() const, g_action_group_list_actions)
+#m4 _CONVERSION(`gchar**',`std::vector<Glib::ustring>',`Glib::ArrayHandler<Glib::ustring>::array_to_vector($3, Glib::OWNERSHIP_DEEP)')
+ _WRAP_METHOD(std::vector<Glib::ustring> list_actions() const, g_action_group_list_actions)
_WRAP_METHOD(bool get_action_enabled(const Glib::ustring& action_name) const, g_action_group_get_action_enabled)
diff --git a/gio/src/application.ccg b/gio/src/application.ccg
index 3b72e42..9f0a410 100644
--- a/gio/src/application.ccg
+++ b/gio/src/application.ccg
@@ -179,34 +179,19 @@ void Gio::Application::on_open(const Application::type_vec_files& files, const G
);
if(base && base->open) {
- typedef GFile* cpointer;
- cpointer* files_array = new cpointer[files.size()];
- guint i = 0;
- for(Application::type_vec_files::const_iterator iter = files.begin(); iter != files.end(); iter++)
- {
- Application::type_vec_files::const_reference refPtr = *iter;
- files_array[i] = refPtr->gobj();
- }
-
- (*base->open)(gobj(), files_array, files.size(), hint.c_str());
+ (*base->open)(gobj(),
+ Glib::ArrayHandler<type_vec_files::value_type>::vector_to_array(files).data(),
+ files.size(),
+ hint.c_str());
}
}
void Application::open(const type_vec_files& files, const Glib::ustring& hint)
{
- //TODO: Create a templated helper function for this:
- typedef GFile* cpointer;
- cpointer* files_array = new cpointer[files.size()];
- guint i = 0;
- for(type_vec_files::const_iterator iter = files.begin(); iter != files.end(); iter++)
- {
- type_vec_files::const_reference refPtr = *iter;
- files_array[i] = refPtr->gobj();
- }
-
- g_application_open(gobj(), files_array, files.size(), hint.c_str());
-
- delete[] files_array ;
+ g_application_open(gobj(),
+ Glib::ArrayHandler<type_vec_files::value_type>::vector_to_array(files).data(),
+ files.size(),
+ hint.c_str());
}
bool Application::register_application()
diff --git a/gio/src/application.hg b/gio/src/application.hg
index abd4b76..bcbd1da 100644
--- a/gio/src/application.hg
+++ b/gio/src/application.hg
@@ -135,6 +135,7 @@ public:
* @newin{2,28}
*/
void open(const type_vec_files& files, const Glib::ustring& hint = Glib::ustring());
+ _IGNORE(g_application_open)
_WRAP_METHOD(int run(int argc, char** argv), g_application_run)
//TODO: g_application_run_with_arguments)
diff --git a/gio/src/applicationcommandline.hg b/gio/src/applicationcommandline.hg
index f840536..8d67ab5 100644
--- a/gio/src/applicationcommandline.hg
+++ b/gio/src/applicationcommandline.hg
@@ -43,11 +43,21 @@ public:
_WRAP_METHOD(void set_exit_status(int exit_status), g_application_command_line_set_exit_status)
_WRAP_METHOD(int get_exit_status() const, g_application_command_line_get_exit_status)
- //TODO: Documentation
+ /** Formats a message and prints it using the stdout print handler in the invoking process.
+ * If this is a local invocation then this is exactly equivalent to g_print().
+ * If this is remote then this is equivalent to calling g_print() in the invoking process.
+ *
+ * @param message The text to print.
+ */
void print(const Glib::ustring& message);
_IGNORE(g_application_command_line_print)
- //TODO: Documentation
+ /** Formats a message and prints it using the stderr print handler in the invoking process.
+ * If this is a local invocation then this is exactly equivalent to g_printerr().
+ * If this is remote then this is equivalent to calling g_printerr() in the invoking process.
+ *
+ * @param message The text to print.
+ */
void printerr(const Glib::ustring& message);
_IGNORE(g_application_command_line_printerr)
};
diff --git a/gio/src/bufferedinputstream.hg b/gio/src/bufferedinputstream.hg
index f8b07b8..598053c 100644
--- a/gio/src/bufferedinputstream.hg
+++ b/gio/src/bufferedinputstream.hg
@@ -52,9 +52,19 @@ protected:
_WRAP_CTOR(BufferedInputStream(const Glib::RefPtr<InputStream>& base_stream, gsize buffer_size), g_buffered_input_stream_new_sized)
public:
+ /** Creates a new InputStream from the given base_stream, with a buffer set to the default size (4 kilobytes).
+ *
+ * @param base_stream An InputStream.
+ * @result an InputStream for the given base_stream.
+ */
_WRAP_CREATE(const Glib::RefPtr<InputStream>& base_stream)
- //TODO: Documentation
+ /** Creates a new InputStream from the given base_stream, with a buffer set to size.
+ *
+ * @param base_stream An InputStream.
+ * @param size A size.
+ * @result an InputStream for the given base_stream.
+ */
static Glib::RefPtr<BufferedInputStream> create_sized(const Glib::RefPtr<InputStream>& base_stream, gsize buffer_size);
_WRAP_METHOD(gsize get_buffer_size() const, g_buffered_input_stream_get_buffer_size)
diff --git a/gio/src/bufferedoutputstream.hg b/gio/src/bufferedoutputstream.hg
index f561c82..3a1ecca 100644
--- a/gio/src/bufferedoutputstream.hg
+++ b/gio/src/bufferedoutputstream.hg
@@ -48,9 +48,19 @@ protected:
_WRAP_CTOR(BufferedOutputStream(const Glib::RefPtr<OutputStream>& base_stream, gsize buffer_size), g_buffered_output_stream_new_sized)
public:
+ /** Creates a new buffered output stream for a base stream.
+ *
+ * @param base_stream An InputStream.
+ * @result an OutputStream for the given base stream.
+ */
_WRAP_CREATE(const Glib::RefPtr<OutputStream>& base_stream)
- //TODO: Documentation
+ /** Creates a new buffered output stream with a given buffer size.
+ *
+ * @param base_stream An InputStream.
+ * @param size A size.
+ * @result an OutputStream with an internal buffer set to size.
+ */
static Glib::RefPtr<BufferedOutputStream> create_sized(const Glib::RefPtr<OutputStream>& base_stream, gsize buffer_size);
_WRAP_METHOD(gsize get_buffer_size() const, g_buffered_output_stream_get_buffer_size)
diff --git a/gio/src/datainputstream.hg b/gio/src/datainputstream.hg
index a2e966f..023e496 100644
--- a/gio/src/datainputstream.hg
+++ b/gio/src/datainputstream.hg
@@ -172,7 +172,7 @@ public:
*/
bool read_until(std::string& data, const std::string& stop_chars);
- //TODO: This will be really deprecated sometime, maybe even before glib 2.28.0.
+ //TODO: This will be really deprecated sometime after glib 2.28.0.
/** The asynchronous version of read_until(). It is
* an error to have two outstanding calls to this function.
*
@@ -195,7 +195,7 @@ public:
void read_until_async(const std::string& stop_chars, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
_IGNORE(g_data_input_stream_read_until_async)
- //TODO: This will be really deprecated sometime, maybe even before glib 2.28.0.
+ //TODO: This will be really deprecated sometime after glib 2.28.0.
/** Finish an asynchronous call started by read_until_async().
*
* @param result The AsyncResult that was provided to the callback slot.
diff --git a/gio/src/dbusmessage.hg b/gio/src/dbusmessage.hg
index 25afc3b..ba11428 100644
--- a/gio/src/dbusmessage.hg
+++ b/gio/src/dbusmessage.hg
@@ -53,9 +53,9 @@ public:
_WRAP_METHOD_DOCS_ONLY(g_dbus_message_new)
_WRAP_CREATE()
- // TODO: We can't use _WRAP_CTOR() and _WRAP_CREATE() because the C functions do more than just call g_object_new():
- // http://bugzilla.gnome.org/show_bug.cgi?id=624977
- // TODO: Should these paramters be ustring or std::string?
+ // Note that we can't use _WRAP_CTOR() and _WRAP_CREATE() because the C functions do more than just call g_object_new():
+ // See http://bugzilla.gnome.org/show_bug.cgi?id=624977
+ // TODO: Should these parameters be ustring or std::string?
_WRAP_METHOD(static Glib::RefPtr<DBusMessage> create_signal(const Glib::ustring& path, const Glib::ustring& interface, const Glib::ustring& signal), g_dbus_message_new_signal)
_WRAP_METHOD(static Glib::RefPtr<DBusMessage> create_method_call(const Glib::ustring& name, const Glib::ustring& path, const Glib::ustring& interface, const Glib::ustring& method), g_dbus_message_new_method_call)
_WRAP_METHOD(static Glib::RefPtr<DBusMessage> create_method_reply(const Glib::RefPtr<DBusMessage>& method_call_message), g_dbus_message_new_method_reply)
diff --git a/gio/src/dbusserver.hg b/gio/src/dbusserver.hg
index 813e020..d9e1e9c 100644
--- a/gio/src/dbusserver.hg
+++ b/gio/src/dbusserver.hg
@@ -47,7 +47,7 @@ class DBusServer : public Glib::Object, public Initable
protected:
-//TODO: Uncomment when bug #639478 is resolved.
+//TODO: Uncomment when this bug is resolved: https://bugzilla.gnome.org/show_bug.cgi?id=639478
/*
DBusServer(const std::string& address,
const std::string& guid,
diff --git a/gio/src/desktopappinfo.hg b/gio/src/desktopappinfo.hg
index ed0ec90..c57c03f 100644
--- a/gio/src/desktopappinfo.hg
+++ b/gio/src/desktopappinfo.hg
@@ -41,7 +41,7 @@ class DesktopAppInfo
public:
// TODO: should use _WRAP_CREATE(), but these functions do more than just call
- // g_object_new() because there's quite a bit of error-handling to do
+ // g_object_new() because there's quite a bit of error-handling to do.
_WRAP_METHOD(static Glib::RefPtr<DesktopAppInfo> create(const std::string& desktop_id), g_desktop_app_info_new)
_WRAP_METHOD(static Glib::RefPtr<DesktopAppInfo> create_from_keyfile(Glib::KeyFile& key_file), g_desktop_app_info_new_from_keyfile)
_WRAP_METHOD(static Glib::RefPtr<DesktopAppInfo> create_from_filename(const std::string& filename), g_desktop_app_info_new_from_filename)
diff --git a/gio/src/emblem.hg b/gio/src/emblem.hg
index 3b093b6..3b0fa37 100644
--- a/gio/src/emblem.hg
+++ b/gio/src/emblem.hg
@@ -47,12 +47,27 @@ class Emblem
_IMPLEMENTS_INTERFACE(Icon)
protected:
- //TODO: Documentation:
+ /** Creates a new emblem for @a icon.
+ * @param icon A Gio::Icon containing the icon.
+ */
_WRAP_CTOR(Emblem(const Glib::RefPtr<Icon>& icon), g_emblem_new)
+
+ /** Creates a new emblem for @a icon.
+ * @param icon A Gio::Icon containing the icon.
+ * @param origin An EmblemOrigin value defining the emblem's origin
+ */
_WRAP_CTOR(Emblem(const Glib::RefPtr<Icon>& icon, EmblemOrigin origin), g_emblem_new_with_origin)
public:
+ /** Creates a new emblem for @a icon.
+ * @param icon A Gio::Icon containing the icon.
+ */
_WRAP_CREATE(const Glib::RefPtr<Icon>& icon)
+
+ /** Creates a new emblem for @a icon.
+ * @param icon A Gio::Icon containing the icon.
+ * @param origin An EmblemOrigin value defining the emblem's origin
+ */
_WRAP_CREATE(const Glib::RefPtr<Icon>& icon, EmblemOrigin origin)
_WRAP_METHOD(Glib::RefPtr<Icon> get_icon(), g_emblem_get_icon)
diff --git a/gio/src/emblemedicon.ccg b/gio/src/emblemedicon.ccg
index c146baa..695e1d5 100644
--- a/gio/src/emblemedicon.ccg
+++ b/gio/src/emblemedicon.ccg
@@ -22,4 +22,10 @@
namespace Gio
{
+EmblemedIcon::EmblemedIcon(const Glib::RefPtr<Icon>& icon)
+:
+ _CONSTRUCT("icon", Glib::unwrap(icon))
+{
+}
+
} //namespace Gio
diff --git a/gio/src/emblemedicon.hg b/gio/src/emblemedicon.hg
index 86a732c..de0033b 100644
--- a/gio/src/emblemedicon.hg
+++ b/gio/src/emblemedicon.hg
@@ -45,12 +45,39 @@ class EmblemedIcon
_IMPLEMENTS_INTERFACE(Icon)
protected:
- //TODO: Documentation:
+ //We have this constructor because g_emblemed_icon_new() may take a NULL emblem parameter.
+ /** Creates a new emblemed icon for @a icon with the emblem @a emblem.
+ * @param icon An Icon.
+ * @param emblem An Emblem.
+ *
+ * @newin{2,28}
+ */
+ explicit EmblemedIcon(const Glib::RefPtr<Icon>& icon);
+
+ /** Creates a new emblemed icon for @a icon with the emblem @a emblem.
+ * @param icon An Icon.
+ * @param emblem An Emblem.
+ */
_WRAP_CTOR(EmblemedIcon(const Glib::RefPtr<Icon>& icon, const Glib::RefPtr<Emblem>& emblem), g_emblemed_icon_new)
public:
+
+ /** Creates a new emblemed icon for @a icon with the emblem @a emblem.
+ * @param icon An Icon.
+ * @param emblem An Emblem.
+ * @result An Icon.
+ */
_WRAP_CREATE(const Glib::RefPtr<Icon>& icon, const Glib::RefPtr<Emblem>& emblem)
+ /** Creates a new emblemed icon for @a icon with no emblem.
+ * @param icon An Icon.
+ * @result An Icon.
+ *
+ * @newin{2,28}
+ */
+ _WRAP_CREATE(const Glib::RefPtr<Icon>& icon)
+
+
_WRAP_METHOD(Glib::RefPtr<Icon> get_icon(), g_emblemed_icon_get_icon)
_WRAP_METHOD(Glib::RefPtr<const Icon> get_icon() const, g_emblemed_icon_get_icon, constversion)
#m4 _CONVERSION(`GList*',`Glib::ListHandle<Glib::RefPtr<Emblem> >',`$2($3, Glib::OWNERSHIP_NONE)')
diff --git a/gio/src/file.hg b/gio/src/file.hg
index b6131b1..0000e4a 100644
--- a/gio/src/file.hg
+++ b/gio/src/file.hg
@@ -1122,12 +1122,20 @@ public:
g_file_set_display_name_finish,
errthrow)
- //TODO: remember to add the docs manually, as we name the method differently.
+ /** Deletes a file.
+ * If the file is a directory, it will only be deleted if it is empty.
+ * The operation can be cancelled by triggering the cancellable object from another thread.
+ * If the operation was cancelled, a Glib::FileError with ERROR_CANCELLED will be thrown.
+ *
+ * @param cancellable A Cancellable object which can be used to cancel the operation.
+ * @return <tt>true</tt> if the file was deleted. <tt>false</tt> otherwise.
+ */
_WRAP_METHOD(bool remove(const Glib::RefPtr<Cancellable>& cancellable),
g_file_delete,
errthrow)
/** Deletes a file.
+ * If the file is a directory, it will only be deleted if it is empty.
*
* @return <tt>true</tt> if the file was deleted. <tt>false</tt> otherwise.
*/
@@ -1174,9 +1182,42 @@ public:
*/
bool copy(const Glib::RefPtr<File>& destination, const SlotFileProgress& slot, const Glib::RefPtr<Cancellable>& cancellable, FileCopyFlags flags = FILE_COPY_NONE);
- //TODO: Documentation.
+ /** Copies the file source to the location specified by destination. Can not handle recursive copies of directories.
+ * If the flag FILE_COPY_OVERWRITE is specified an already existing destination file is overwritten.
+ * If the flag FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the source symlink will be copied.
+ *
+ * The operation can be monitored via the @a slot callback.
+ *
+ * If the source file does not exist then a Gio::Error with NOT_FOUND will be thrown, independent on the status of the destination.
+ *
+ * If FILE_COPY_OVERWRITE is not specified and the target exists, then a Gio::Error with EXISTS will be thrown.
+ *
+ * If trying to overwrite a file over a directory a Gio::Error with IS_DIRECTORY will be thrown.
+ * If trying to overwrite a directory with a directory a Gio::Error with WOULD_MERGE will be thrown.
+ *
+ * If the source is a directory and the target does not exist, or FILE_COPY_OVERWRITE is specified and the target is a file,
+ * then a Gio::Error with WOULD_RECURSE will be thrown.
+ *
+ * If you are interested in copying the Gio::File object itself (not the on-disk file), see File::dup().
+ */
bool copy(const Glib::RefPtr<File>& destination, const SlotFileProgress& slot, FileCopyFlags flags = FILE_COPY_NONE);
+ /** Copies the file source to the location specified by destination. Can not handle recursive copies of directories.
+ * If the flag FILE_COPY_OVERWRITE is specified an already existing destination file is overwritten.
+ * If the flag FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the source symlink will be copied.
+ *
+ * If the source file does not exist then a Gio::Error with NOT_FOUND will be thrown, independent on the status of the destination.
+ *
+ * If FILE_COPY_OVERWRITE is not specified and the target exists, then a Gio::Error with EXISTS will be thrown.
+ *
+ * If trying to overwrite a file over a directory a Gio::Error with IS_DIRECTORY will be thrown.
+ * If trying to overwrite a directory with a directory a Gio::Error with WOULD_MERGE will be thrown.
+ *
+ * If the source is a directory and the target does not exist, or FILE_COPY_OVERWRITE is specified and the target is a file,
+ * then a Gio::Error with WOULD_RECURSE will be thrown.
+ *
+ * If you are interested in copying the Gio::File object itself (not the on-disk file), see File::dup().
+ */
bool copy(const Glib::RefPtr<File>& destination, FileCopyFlags flags = FILE_COPY_NONE);
_IGNORE(g_file_copy)
@@ -1997,6 +2038,7 @@ public:
* @param etag_out A location to place the current entity tag for the file.
*/
bool load_contents(const Glib::RefPtr<Cancellable>& cancellable, char*& contents, gsize& length, std::string& etag_out);
+
/** Loads the content of the file into memory, returning the size of the data.
* The data is always zero terminated, but this is not included in the resultant @a length.
*
@@ -2009,6 +2051,7 @@ public:
* @newin{2,22}
*/
bool load_contents(const Glib::RefPtr<Cancellable>& cancellable, char*& contents, gsize& length);
+
//TODO: Something better than char*& for contents?
/** Loads the content of the file into memory, returning the size of the data.
* The data is always zero terminated, but this is not included in the resultant @a length.
@@ -2018,6 +2061,7 @@ public:
* @param etag_out A location to place the current entity tag for the file.
*/
bool load_contents(char*& contents, gsize& length, std::string& etag_out);
+
/** Loads the content of the file into memory, returning the size of the data.
* The data is always zero terminated, but this is not included in the resultant @a length.
*
diff --git a/gio/src/filterinputstream.hg b/gio/src/filterinputstream.hg
index c975c64..db2050b 100644
--- a/gio/src/filterinputstream.hg
+++ b/gio/src/filterinputstream.hg
@@ -26,9 +26,9 @@ _PINCLUDE(giomm/private/inputstream_p.h)
namespace Gio
{
-//TODO: Proper documentation.
-
/** Filter Input Stream.
+ * This is a base class for input stream implementations that perform some kind of filtering operation on a base stream.
+ & Typical examples of filtering operations are character set conversion, compression and byte order flipping.
*
* @ingroup Streams
*
diff --git a/gio/src/filteroutputstream.hg b/gio/src/filteroutputstream.hg
index d6137f9..bb8d3cb 100644
--- a/gio/src/filteroutputstream.hg
+++ b/gio/src/filteroutputstream.hg
@@ -26,10 +26,11 @@ _PINCLUDE(giomm/private/outputstream_p.h)
namespace Gio
{
-//TODO: Proper documentation:
-
/** Filter Output Stream.
*
+ * This is a base class for output stream implementations that perform some kind of filtering operation on a base stream.
+ * Typical examples of filtering operations are character set conversion, compression and byte order flipping.
+ *
* @ingroup Streams
*
* @newin{2,16}
diff --git a/gio/src/memoryoutputstream.hg b/gio/src/memoryoutputstream.hg
index dda0376..d44aa46 100644
--- a/gio/src/memoryoutputstream.hg
+++ b/gio/src/memoryoutputstream.hg
@@ -29,10 +29,10 @@ _PINCLUDE(giomm/private/outputstream_p.h)
namespace Gio
{
-//TODO: Proper documentation:
-
/** Streaming output operations on memory chunks
*
+ * This class uses arbitrary memory chunks as output for GIO streaming output operations.
+ *
* @ingroup Streams
*
* @newin{2,20}
diff --git a/gio/src/proxy.hg b/gio/src/proxy.hg
index 12ac8a8..d31d955 100644
--- a/gio/src/proxy.hg
+++ b/gio/src/proxy.hg
@@ -56,10 +56,12 @@ public:
_WRAP_METHOD(Glib::RefPtr<IOStream> connect(const Glib::RefPtr<IOStream>& connection,
const Glib::RefPtr<const ProxyAddress>& proxy_adress, const Glib::RefPtr<Cancellable>& cancellable), g_proxy_connect, errthrow)
- //TODO: Documentation
+ /** An Asynchronous version of connect().
+ */
void connect_async(const Glib::RefPtr<IOStream>& connection, const Glib::RefPtr<const ProxyAddress>& proxy_address, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
- //TODO: Documentation
+ /** An Asynchronous version of connect().
+ */
void connect_async(const Glib::RefPtr<IOStream>& connection, const Glib::RefPtr<const ProxyAddress>& proxy_address, const SlotAsyncReady& slot);
_IGNORE(g_proxy_connect_async)
diff --git a/gio/src/proxyresolver.ccg b/gio/src/proxyresolver.ccg
index d34fdcd..ae51746 100644
--- a/gio/src/proxyresolver.ccg
+++ b/gio/src/proxyresolver.ccg
@@ -26,10 +26,11 @@
namespace Gio
{
-Glib::StringArrayHandle ProxyResolver::lookup(const Glib::ustring& uri)
+std::vector<Glib::ustring> ProxyResolver::lookup(const Glib::ustring& uri)
{
GError* gerror = 0;
- Glib::StringArrayHandle retvalue = Glib::StringArrayHandle(g_proxy_resolver_lookup(gobj(), uri.c_str(), 0, &(gerror)), Glib::OWNERSHIP_DEEP);
+ std::vector<Glib::ustring> retvalue =
+ Glib::ArrayHandler<Glib::ustring>::array_to_vector(g_proxy_resolver_lookup(gobj(), uri.c_str(), 0, &(gerror)), Glib::OWNERSHIP_DEEP);
if(gerror)
::Glib::Error::throw_exception(gerror);
diff --git a/gio/src/proxyresolver.hg b/gio/src/proxyresolver.hg
index 387e813..df90c01 100644
--- a/gio/src/proxyresolver.hg
+++ b/gio/src/proxyresolver.hg
@@ -52,22 +52,38 @@ public:
_WRAP_METHOD(bool is_supported() const, g_proxy_resolver_is_supported)
//TODO: Use std::string instead of ustring (StringArrayHandle uses ustring)?:
-#m4 _CONVERSION(`gchar**',`Glib::StringArrayHandle',`Glib::StringArrayHandle($3, Glib::OWNERSHIP_DEEP)')
- _WRAP_METHOD(Glib::StringArrayHandle lookup(const Glib::ustring& uri,
+#m4 _CONVERSION(`gchar**',`std::vector<Glib::ustring>',`Glib::ArrayHandler<Glib::ustring>::array_to_vector($3, Glib::OWNERSHIP_DEEP)')
+ _WRAP_METHOD(std::vector<Glib::ustring> lookup(const Glib::ustring& uri,
const Glib::RefPtr<Cancellable>& cancellable), g_proxy_resolver_lookup, errthrow)
- //TODO: Documentation
- Glib::StringArrayHandle lookup(const Glib::ustring& uri);
+ /** Looks into the system proxy configuration to determine what proxy, if any, to use to connect to uri.
+ * The returned proxy URIs are of the form <protocol>://[user[:password] ]host:port or direct://, where <protocol> could be http, rtsp, socks or other proxying protocol.
+ *
+ * If you don't know what network protocol is being used on the socket, you should use none as the URI protocol.
+ * In this case, the resolver might still return a generic proxy type (such as SOCKS), but would not return protocol-specific proxy types (such as http).
+ *
+ * direct:// is used when no proxy is needed. Direct connection should not be attempted unless it is part of the returned array of proxies.
+ *
+ * @param uri a URI representing the destination to connect to.
+ */
+ std::vector<Glib::ustring> lookup(const Glib::ustring& uri);
- //TODO: Documentation
+ /** Asynchronous lookup of proxy. See lookup() for more details.
+ * @param uri a URI representing the destination to connect to.
+ * @param slot A callback slot to call after the resolution completes.
+ * @param cancellable A Cancellable object which can be used to cancel the operation.
+ */
void lookup_async(const Glib::ustring& uri, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
- //TODO: Documentation
+ /** Asynchronous lookup of proxy. See lookup() for more details.
+ * @param uri a URI representing the destination to connect to.
+ * @param slot A callback slot to call after the resolution completes.
+ */
void lookup_async(const Glib::ustring& uri, const SlotAsyncReady& slot);
_IGNORE(g_proxy_resolver_lookup_async)
- _WRAP_METHOD(Glib::StringArrayHandle lookup_finish(const Glib::RefPtr<AsyncResult>& result), g_proxy_resolver_lookup_finish, errthrow)
+ _WRAP_METHOD(std::vector<Glib::ustring> lookup_finish(const Glib::RefPtr<AsyncResult>& result), g_proxy_resolver_lookup_finish, errthrow)
};
diff --git a/gio/src/resolver.hg b/gio/src/resolver.hg
index 589c7a2..61cc642 100644
--- a/gio/src/resolver.hg
+++ b/gio/src/resolver.hg
@@ -61,13 +61,34 @@ public:
#m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<InetAddress> >',`$2($3, Glib::OWNERSHIP_DEEP)')
_WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name(const Glib::ustring& hostname, const Glib::RefPtr<Cancellable>& cancellable), g_resolver_lookup_by_name, errthrow)
- //TODO: Documentation
+ /** Synchronously resolves hostname to determine its associated IP address(es).
+ * @a hostname may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around InetAddress:create_from_string()).
+ *
+ * On success, this will return a list of InetAddress, sorted in order of preference. (That is, you should attempt to connect to the first address first, then the second if the first fails, etc.)
+ *
+ * If the DNS resolution fails, a ResolverError exception will be thrown.
+ *
+ * If you are planning to connect to a socket on the resolved IP address, it may be easier to create a NetworkAddress and use its SocketConnectable base class.
+ *
+ * @param hostname hostname The hostname to look up.
+ */
Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name(const Glib::ustring& hostname);
- //TODO: Documentation
+ /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call
+ * lookup_by_name_finish() to get the result. See lookup_by_name() for more details.
+ *
+ * @param hostname hostname The hostname to look up.
+ * @param slot A callback slot to call after the resolution completes.
+ * @param cancellable A Cancellable object which can be used to cancel the operation.
+ */
void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
- //TODO: Documentation
+ /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call
+ * lookup_by_name_finish() to get the result. See lookup_by_name() for more details.
+ *
+ * @param hostname hostname The hostname to look up.
+ * @param slot A callback slot to call after the resolution completes.
+ */
void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot);
_IGNORE(g_resolver_lookup_by_name_async)
@@ -75,11 +96,32 @@ public:
_WRAP_METHOD(Glib::ustring lookup_by_address(const Glib::RefPtr<InetAddress>& address, const Glib::RefPtr<Cancellable>& cancellable), g_resolver_lookup_by_address, errthrow)
- //TODO: Documentation
+ /** Synchronously reverse-resolves an address to determine its associated hostname.
+ *
+ * If the DNS resolution fails then a ResolverError exception will be thrown.
+ *
+ * @param address The address to reverse-resolve.
+ * @result A hostname (either ASCII-only, or in ASCII-encoded form), or an empty string on error.
+ */
Glib::ustring lookup_by_address(const Glib::RefPtr<InetAddress>& address);
+
+ /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call
+ * lookup_by_address_finish() to get the final result.
+ *
+ * @param address The address to reverse-resolve.
+ * @param hostname hostname The hostname to look up.
+ * @param slot A callback slot to call after the resolution completes.
+ * @param cancellable A Cancellable object which can be used to cancel the operation.
+ */
void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
- //TODO: Documentation
+ /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call
+ * lookup_by_address_finish() to get the final result.
+ *
+ * @param address The address to reverse-resolve.
+ * @param hostname hostname The hostname to look up.
+ * @param slot A callback slot to call after the resolution completes.
+ */
void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot);
_IGNORE(g_resolver_lookup_by_address_async)
@@ -88,13 +130,41 @@ public:
#m4 _CONVERSION(`GList*',`ListHandle_SrvTarget',`$2($3, Glib::OWNERSHIP_DEEP)')
_WRAP_METHOD(ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const Glib::RefPtr<Cancellable>& cancellable), g_resolver_lookup_service, errthrow)
- //TODO: Documentation
+ /** Synchronously performs a DNS SRV lookup for the given service and protocol in the given domain and returns an list of SrvTargets.
+ * @a domain may be an ASCII-only or UTF-8 hostname. Note also that the service and protocol arguments do not include the leading underscore that appears in the actual DNS entry.
+ *
+ * On success, this will return a list of SrvTargets, sorted in order of preference.
+ * (That is, you should attempt to connect to the first target first, then the second if the first fails, etc.)
+ *
+ * If the DNS resolution fails a ResolverError exception will be thrown.
+ *
+ * If you are planning to connect to the service, it is usually easier to create a NetworkService and use its SocketConnectable base class interface. \
+ *
+ * @param service The service type to look up (eg, "ldap").
+ * @param protocol The networking protocol to use for service (eg, "tcp")
+ * @param domain The DNS domain to look up the service in.
+ */
ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain);
- //TODO: Documentation
+ /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback,
+ * which must call lookup_service_finish() to get the final result. See glookup_service() for more details.
+ *
+ * @param service The service type to look up (eg, "ldap").
+ * @param protocol The networking protocol to use for service (eg, "tcp")
+ * @param domain The DNS domain to look up the service in.
+ * @param slot A callback slot to call after the resolution completes.
+ * @param cancellable A Cancellable object which can be used to cancel the operation.
+ */
void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
- //TODO: Documentation
+ /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback,
+ * which must call lookup_service_finish() to get the final result. See glookup_service() for more details.
+ *
+ * @param service The service type to look up (eg, "ldap").
+ * @param protocol The networking protocol to use for service (eg, "tcp")
+ * @param domain The DNS domain to look up the service in.
+ * @param slot A callback slot to call after the resolution completes.
+ */
void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot);
_IGNORE(g_resolver_lookup_service_async)
diff --git a/gio/src/seekable.hg b/gio/src/seekable.hg
index df8ae00..869f737 100644
--- a/gio/src/seekable.hg
+++ b/gio/src/seekable.hg
@@ -53,7 +53,7 @@ public:
_WRAP_METHOD(bool seek(goffset offset, Glib::SeekType type, const Glib::RefPtr<Cancellable>& cancellable), g_seekable_seek, errthrow)
- //TODO: Document the exception: http://bugzilla.gnome.org/show_bug.cgi?id=509990
+ //TODO: Document the exception in the C API: https://bugzilla.gnome.org/show_bug.cgi?id=509990#c1
/** Seeks in the stream by the given @a offset, modified by @a type .
*
* @param offset A #goffset.
@@ -67,7 +67,7 @@ public:
_WRAP_METHOD(bool truncate(goffset offset, const Glib::RefPtr<Cancellable>& cancellable), g_seekable_truncate, errthrow)
- //TODO: Document the exception: http://bugzilla.gnome.org/show_bug.cgi?id=509990
+ //TODO: Document the exception in the C API: https://bugzilla.gnome.org/show_bug.cgi?id=509990#c1
/** Truncates a stream with a given #offset.
*
* @param offset A #goffset.
diff --git a/gio/src/settings.hg b/gio/src/settings.hg
index 231e0f8..1d85bba 100644
--- a/gio/src/settings.hg
+++ b/gio/src/settings.hg
@@ -52,7 +52,7 @@ public:
_WRAP_METHOD(bool set_value(const Glib::ustring& key, const Glib::VariantBase& value), g_settings_set_value)
- /** TODO: Gets the value that is stored in the settings for a @key.
+ /** Gets the value that is stored in the settings for a @key.
*
* It is a programmer error to give a @a key that isn't contained in the
* schema for the settings.
@@ -98,10 +98,13 @@ public:
_WRAP_METHOD(void reset(const Glib::ustring& key), g_settings_reset)
- //TODO: _WRAP_METHOD(Glib::StringArrayHandle list_schemas() const, g_settings_list_schemas)
+#m4 _CONVERSION(`gchar**',`std::vector<Glib::ustring>',`Glib::ArrayHandler<Glib::ustring>::array_to_vector($3, Glib::OWNERSHIP_NONE)')
+ _WRAP_METHOD(std::vector<Glib::ustring> list_schemas() const, g_settings_list_schemas)
+
+#m4 _CONVERSION(`gchar**',`std::vector<Glib::ustring>',`Glib::ArrayHandler<Glib::ustring>::array_to_vector($3, Glib::OWNERSHIP_DEEP)')
+ _WRAP_METHOD(std::vector<Glib::ustring> list_children() const, g_settings_list_children)
+ _WRAP_METHOD(std::vector<Glib::ustring> list_keys() const, g_settings_list_keys)
- _WRAP_METHOD(Glib::StringArrayHandle list_children() const, g_settings_list_children)
- _WRAP_METHOD(Glib::StringArrayHandle list_keys() const, g_settings_list_keys)
//TODO: Choose an appropriate Variant template type: GVariant* g_settings_get_range(const gchar* key)
_WRAP_METHOD(bool range_check(const Glib::ustring& key, const Glib::VariantBase& value) const, g_settings_range_check)
diff --git a/gio/src/socket.hg b/gio/src/socket.hg
index be19c69..78db210 100644
--- a/gio/src/socket.hg
+++ b/gio/src/socket.hg
@@ -115,13 +115,13 @@ public:
static Glib::RefPtr<Socket> create_from_fd(int fd, const Glib::RefPtr<Cancellable>&
cancellable = Glib::RefPtr<Cancellable>());
- //TODO: Writecusotm documetation, mentioning, for instance, the exception, instead of a bool return.
+ //TODO: Write custom documetation, mentioning, for instance, the exception, instead of a bool return.
_WRAP_METHOD(void bind(const Glib::RefPtr<SocketAddress>& address, bool allow_reuse), g_socket_bind, errthrow)
_WRAP_METHOD(void listen(), g_socket_listen, errthrow)
_WRAP_METHOD(Glib::RefPtr<Socket> accept(const Glib::RefPtr<Cancellable>& cancellable), g_socket_accept, errthrow)
Glib::RefPtr<Socket> accept();
- //TODO: Writecusotm documetation, mentioning, for instance, the exception, instead of a bool return.
+ //TODO: Write custom documetation, mentioning, for instance, the exception, instead of a bool return.
_WRAP_METHOD(void connect(const Glib::RefPtr<SocketAddress>& address, const Glib::RefPtr<Cancellable>& cancellable), g_socket_connect, errthrow)
void connect(const Glib::RefPtr<SocketAddress>& address);
diff --git a/gio/src/socketaddressenumerator.hg b/gio/src/socketaddressenumerator.hg
index 6cdfd65..6056c7c 100644
--- a/gio/src/socketaddressenumerator.hg
+++ b/gio/src/socketaddressenumerator.hg
@@ -41,14 +41,35 @@ class SocketAddressEnumerator : public Glib::Object
public:
_WRAP_METHOD(Glib::RefPtr<SocketAddress> next(const Glib::RefPtr<Cancellable>& cancellable), g_socket_address_enumerator_next, errthrow)
- //TODO: Docs.
+ /** Retrieves the next SocketAddress from the enumerator.
+ * Note that this may block for some amount of time. (Eg, a NetworkAddress may need to do a DNS lookup before it can return an address.)
+ * Use next_async() if you need to avoid blocking.
+ *
+ * If this enumerator is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error),
+ * then the first call to next() will throw an exception. However, if the first call to next() succeeds, then any further internal errors
+ * will be ignored.
+ *
+ * When there are no further addresses, an exception will be thrown.
+ *
+ * @result A SocketAddress
+ */
Glib::RefPtr<SocketAddress> next();
- _IGNORE(g_socket_address_enumerator_next_async)
+ /** Asynchronously retrieves the next SocketAddress from the enumerator and then calls @a slot,
+ * which must call next_finish() to get the result.
+ *
+ * @param cancellable A Cancellable object which can be used to cancel the operation.
+ * @param slot A callback slot to call after the resolution completes.
+ */
void next_async(const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
- //TODO: Docs.
+ /** Asynchronously retrieves the next SocketAddress from the enumerator and then calls @a slot,
+ * which must call next_finish() to get the result.
+ *
+ * @param slot A callback slot to call after the resolution completes.
+ */
void next_async(const SlotAsyncReady& slot);
+ _IGNORE(g_socket_address_enumerator_next_async)
_WRAP_METHOD(Glib::RefPtr<SocketAddress> next_finish(const Glib::RefPtr<AsyncResult>& result), g_socket_address_enumerator_next_finish, errthrow)
};
diff --git a/gio/src/socketclient.hg b/gio/src/socketclient.hg
index 6c7a862..bb59400 100644
--- a/gio/src/socketclient.hg
+++ b/gio/src/socketclient.hg
@@ -73,7 +73,24 @@ Glib::RefPtr<SocketConnection> connect(const Glib::RefPtr<SocketConnectable>& co
_WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_to_host(const Glib::ustring& host_and_port, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable), g_socket_client_connect_to_host, errthrow)
- //TODO: Documentation
+ /** This is a helper function for connect().
+ * This attempts to create a TCP connection to the named host.
+ *
+ * @a host_and_port may be in any of a number of recognised formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed).
+ *
+ * If no port override is given in @a host_and_port then default_port will be used as the port number to connect to.
+ *
+ * In general, @a host_and_port is expected to be provided by the user (allowing them to give the hostname, and a port overide if necessary) and default_port is expected to be provided by the application.
+ *
+ * In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds.
+ *
+ * Upon a successful connection, a new SocketConnection is constructed and returned.
+ *
+ * In the event of any failure (DNS error, service not found, no hosts connectable) an exception is thrown.
+ *
+ * @param host_and_port The name and optionally port of the host to connect to.
+ * @param default_port The default port to connect to.
+ */
Glib::RefPtr<SocketConnection> connect_to_host(const Glib::ustring& host_and_port, guint16 default_port);
_WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, const Glib::ustring& service, const Glib::RefPtr<Cancellable>& cancellable), g_socket_client_connect_to_service, errthrow)
@@ -81,13 +98,31 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
_WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_to_uri(const Glib::ustring& uri, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable), g_socket_client_connect_to_uri, errthrow)
- //TODO: Documentation
+ /** This is a helper function for connect().
+ * This attempts to create a TCP connection with a network URI.
+ *
+ * @a uri may be any valid URI containing an "authority" (hostname/port) component. If a port is not specified in the URI, default_port will be used. TLS will be negotiated if "tls" is true. (GSocketClient does not know to automatically assume TLS for certain URI schemes.)
+ *
+ * Using this rather than connect() or connect_to_host() allows SocketClient to determine when to use application-specific proxy protocols.
+ *
+ * Upon a successful connection, a new SocketConnection is constructed and returned.
+ *
+ * In the event of any failure (DNS error, service not found, no hosts connectable) an exception is thrown.
+ *
+ * @param uri A network URI
+ * @param default_port The default port to connect to.
+ */
Glib::RefPtr<SocketConnection> connect_to_uri(const Glib::ustring& uri, guint16 default_port);
_WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_async)
void connect_async(const Glib::RefPtr<SocketConnectable>& connectable, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
- //TODO: Documentation
+ /** This is the asynchronous version of connect().
+ * When the operation is finished @a slot will be called. You can then call finish() to get the result of the operation.
+ *
+ * @param connectable A SocketConnectable specifying the remote address.
+ * @param slot A callback slot to call after the operation completes.
+ */
void connect_async(const Glib::RefPtr<SocketConnectable>& connectable, const SlotAsyncReady& slot);
_IGNORE(g_socket_client_connect_async)
@@ -97,7 +132,13 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
_WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_to_host_async)
void connect_to_host_async(const Glib::ustring& host_and_port, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
- //TODO: Documentation
+ /** This is the asynchronous version of connect_to_host().
+ * When the operation is finished @a slot will be called. You can then call connect_to_host_finish() to get the result of the operation.
+ *
+ * @param host_and_port The name and optionally the port of the host to connect to.
+ * @param default_port The default port to connect to.
+ * @param slot A callback slot to call after the opration completes.
+ */
void connect_to_host_async(const Glib::ustring& host_and_port, guint16 default_port, const SlotAsyncReady& slot);
_IGNORE(g_socket_client_connect_to_host_async)
@@ -107,7 +148,12 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
_WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_to_service_async)
void connect_to_service_async(const Glib::ustring& domain, const Glib::ustring& service, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
- //TODO: Documentation
+ /** This is the asynchronous version of connect_to_service().
+ *
+ * @param domain A domain name.
+ * @param service The name of the service to connect to
+ * @param slot A callback slot to call after the opration completes.
+ */
void connect_to_service_async(const Glib::ustring& domain, const Glib::ustring& service, const SlotAsyncReady& slot);
_IGNORE(g_socket_client_connect_to_service_async)
@@ -117,7 +163,12 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
_WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_to_uri_async)
void connect_to_uri_async(const Glib::ustring& uri, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
- //TODO: Documentation
+ /** This is the asynchronous version of connect_to_uri().
+ *
+ * @param uri A network URI.
+ * @param default_port The default port to connect to.
+ * @param slot A callback slot to call after the opration completes.
+ */
void connect_to_uri_async(const Glib::ustring& uri, guint16 default_port, const SlotAsyncReady& slot);
_IGNORE(g_socket_client_connect_to_uri_async)
@@ -133,11 +184,10 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
_WRAP_METHOD(void add_application_proxy(const Glib::ustring& protocol), g_socket_client_add_application_proxy)
-_WRAP_PROPERTY("family", SocketFamily)
-_WRAP_PROPERTY("local-address", Glib::RefPtr<SocketAddress>)
-_WRAP_PROPERTY("protocol", SocketProtocol)
-_WRAP_PROPERTY("type", SocketType)
-
+ _WRAP_PROPERTY("family", SocketFamily)
+ _WRAP_PROPERTY("local-address", Glib::RefPtr<SocketAddress>)
+ _WRAP_PROPERTY("protocol", SocketProtocol)
+ _WRAP_PROPERTY("type", SocketType)
};
} // namespace Gio
diff --git a/gio/src/socketcontrolmessage.hg b/gio/src/socketcontrolmessage.hg
index fc290e9..ddb5e69 100644
--- a/gio/src/socketcontrolmessage.hg
+++ b/gio/src/socketcontrolmessage.hg
@@ -55,7 +55,7 @@ protected:
_CTOR_DEFAULT
public:
- //TODO?: _WRAP_METHOD(static Glib::RefPtr<SocketControlMessage> deserialize(int level, int type, gsize size, gpointer data), g_socket_control_message_deserialize)
+ _WRAP_METHOD(static Glib::RefPtr<SocketControlMessage> deserialize(int level, int type, gsize size, gpointer data), g_socket_control_message_deserialize)
_WRAP_METHOD(int get_level() const, g_socket_control_message_get_level)
_WRAP_METHOD(int get_msg_type() const, g_socket_control_message_get_msg_type)
_WRAP_METHOD(gsize get_size() const, g_socket_control_message_get_size)
diff --git a/gio/src/themedicon.hg b/gio/src/themedicon.hg
index b7260a9..4243558 100644
--- a/gio/src/themedicon.hg
+++ b/gio/src/themedicon.hg
@@ -47,11 +47,20 @@ class ThemedIcon
_IMPLEMENTS_INTERFACE(Icon)
protected:
- //TODO: Documentation:
+ /** Creates a new themed icon for @ iconname, and optionally all the names that can be created by shortening @a iconname at '-' characters.
+ *
+ * @param iconname A string containing an icon name.
+ * use_default_callbacks Whether to use all the names that can be created by shortening @a iconname at '-' characters.
+ */
explicit ThemedIcon(const std::string& iconname, bool use_default_callbacks = false);
_IGNORE(g_themed_icon_new, g_themed_icon_new_with_default_fallbacks)
public:
+ /** Creates a new themed icon for @ iconname, and optionally all the names that can be created by shortening @a iconname at '-' characters.
+ *
+ * @param iconname A string containing an icon name.
+ * use_default_callbacks Whether to use all the names that can be created by shortening @a iconname at '-' characters.
+ */
_WRAP_CREATE(const std::string& iconname, bool use_default_callbacks = false)
//TODO: GIcon *g_themed_icon_new_from_names (char **iconnames, int len);
@@ -59,7 +68,7 @@ public:
_WRAP_METHOD(void prepend_name(const std::string& iconname), g_themed_icon_prepend_name)
_WRAP_METHOD(void append_name(const std::string& iconname), g_themed_icon_append_name)
- //TODO: USe _WRAP_METHOD() instead, but:
+ //TODO: Use _WRAP_METHOD() instead, but:
//#m4 _CONVERSION(`const char*const*',`Glib::StringArrayHandle',`Glib::StringArrayHandle($3, Glib::OWNERSHIP_DEEP)')
//TODO: gmmproc complains about the wrong number of arguments, but I can't see why. murrayc.
//_WRAP_METHOD(Glib::StringArrayHandle get_names() const, g_themed_icon_get_names)
diff --git a/glib/src/optioncontext.hg b/glib/src/optioncontext.hg
index 9ec718c..eda2238 100644
--- a/glib/src/optioncontext.hg
+++ b/glib/src/optioncontext.hg
@@ -91,7 +91,14 @@ public:
#m4 _CONVERSION(`const OptionGroup&',`GOptionGroup*',`const_cast<GOptionGroup*>(($3).gobj())')
_WRAP_METHOD(Glib::ustring get_help(bool main_help, const OptionGroup& group) const, g_option_context_get_help)
- //TODO: Documentation.
+ /** Returns a formatted, translated help text for the given context.
+ * To obtain the text produced by --help, call get_help (true).
+ * To obtain the text produced by --help-all, call get_help(false).
+ * To obtain the help text for an option group, call get_help(false, group).
+ *
+ * @param main_help If true, only include the main group.
+ * @result string containing the help text.
+ */
Glib::ustring get_help(bool main_help = true) const;
GOptionContext* gobj() { return gobject_; }
diff --git a/glib/src/varianttype.hg b/glib/src/varianttype.hg
index fae804f..9942ef7 100644
--- a/glib/src/varianttype.hg
+++ b/glib/src/varianttype.hg
@@ -97,8 +97,12 @@ public:
*/
explicit VariantType(const GVariantType* castitem);
- //TODO: Docuementation
+ /** Creates a new VariantType corresponding to the type string given by @a type_string.
+ *
+ * It is a programmer error to call this function with an invalid type string. Use string_is_valid() if you are unsure.
+ */
explicit VariantType(const std::string& type_string);
+ _IGNORE(g_variant_type_new)
VariantType& operator=(const GVariantType* castitem);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
