[glibmm] Add some documentation.
- From: Murray Cumming <murrayc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glibmm] Add some documentation.
- Date: Sun, 21 Oct 2012 11:49:52 +0000 (UTC)
commit 6b944f4fcaad845efa6e212eae22fee4a2927693
Author: Murray Cumming <murrayc murrayc com>
Date: Sun Oct 21 13:49:45 2012 +0200
Add some documentation.
* gio/src/dbusintrospection.hg:
* gio/src/dbusserver.ccg:
* gio/src/inputstream.hg:
* gio/src/menu.hg:
* gio/src/menuitem.hg:
* gio/src/outputstream.hg:
* glib/src/threads.hg: Deal with some TODOS, mostly
adding documentation based on the C documentation.
ChangeLog | 13 +++++++
gio/src/dbusintrospection.hg | 6 ++-
gio/src/dbusserver.ccg | 82 ++++--------------------------------------
gio/src/inputstream.hg | 55 ++++++++++++++++++++++++++--
gio/src/menu.hg | 9 ++++-
gio/src/menuitem.hg | 8 +++-
gio/src/outputstream.hg | 66 +++++++++++++++++++++++++++++++--
glib/src/threads.hg | 19 +++++++++-
8 files changed, 168 insertions(+), 90 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 5071ddd..13dacb1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,18 @@
2012-10-21 Murray Cumming <murrayc murrayc com>
+ Add some documentation.
+
+ * gio/src/dbusintrospection.hg:
+ * gio/src/dbusserver.ccg:
+ * gio/src/inputstream.hg:
+ * gio/src/menu.hg:
+ * gio/src/menuitem.hg:
+ * gio/src/outputstream.hg:
+ * glib/src/threads.hg: Deal with some TODOS, mostly
+ adding documentation based on the C documentation.
+
+2012-10-21 Murray Cumming <murrayc murrayc com>
+
Create only .tar.xz tarballs.
* configure.ac: This is what ftp.gnome.org wants, so this avoids
diff --git a/gio/src/dbusintrospection.hg b/gio/src/dbusintrospection.hg
index 729b25d..1e15637 100644
--- a/gio/src/dbusintrospection.hg
+++ b/gio/src/dbusintrospection.hg
@@ -141,10 +141,12 @@ public:
_WRAP_METHOD(Glib::RefPtr<InterfaceInfo> lookup_interface(const Glib::ustring& name), g_dbus_node_info_lookup_interface, refreturn)
_WRAP_METHOD(Glib::RefPtr<const InterfaceInfo> lookup_interface(const Glib::ustring& name) const, g_dbus_node_info_lookup_interface, constversion, refreturn)
- //TODO: Documentation:
+ /** Looks up information about the first interface.
+ */
Glib::RefPtr<InterfaceInfo> lookup_interface();
- //TODO: Documentation:
+ /** Looks up information about the first interface.
+ */
Glib::RefPtr<const InterfaceInfo> lookup_interface() const;
//TODO: _WRAP_METHOD(void generate_xml(guint indent, GString* string_builder), g_dbus_node_info_generate_xml)
diff --git a/gio/src/dbusserver.ccg b/gio/src/dbusserver.ccg
index 9454bf2..8e22657 100644
--- a/gio/src/dbusserver.ccg
+++ b/gio/src/dbusserver.ccg
@@ -87,26 +87,8 @@ Glib::RefPtr<Server> Server::create_sync(const std::string& address,
const Glib::RefPtr<Cancellable>& cancellable,
ServerFlags flags)
{
- //TODO: Use the constructor instead of the code underneath when
- //g_dbus_server_new_sync() does not do more than call g_initable_new().
- //https://bugzilla.gnome.org/show_bug.cgi?id=639478
- //return Glib::RefPtr<Server>(new Server(address, guid, observer,
- //cancellable, flags));
-
- GError* gerror = 0;
-
- Glib::RefPtr<Server> result =
- Glib::wrap(g_dbus_server_new_sync(address.c_str(),
- static_cast<GDBusServerFlags>(flags),
- guid.c_str(),
- Glib::unwrap(observer),
- Glib::unwrap(cancellable),
- &gerror));
-
- if(gerror)
- ::Glib::Error::throw_exception(gerror);
-
- return result;
+ return Glib::RefPtr<Server>(new Server(address, guid, observer,
+ cancellable, flags));
}
Glib::RefPtr<Server> Server::create_sync(const std::string& address,
@@ -114,25 +96,8 @@ Glib::RefPtr<Server> Server::create_sync(const std::string& address,
const Glib::RefPtr<Cancellable>& cancellable,
ServerFlags flags)
{
- //TODO: Use the constructor instead of the code underneath when
- //g_dbus_server_new_sync() does not do more than call g_initable_new().
- //https://bugzilla.gnome.org/show_bug.cgi?id=639478
- //return Glib::RefPtr<Server>(new Server(address, guid,
- //cancellable, flags));
-
- GError* gerror = 0;
-
- Glib::RefPtr<Server> result =
- Glib::wrap(g_dbus_server_new_sync(address.c_str(),
- static_cast<GDBusServerFlags>(flags),
- guid.c_str(), 0,
- Glib::unwrap(cancellable),
- &gerror));
-
- if(gerror)
- ::Glib::Error::throw_exception(gerror);
-
- return result;
+ return Glib::RefPtr<Server>(new Server(address, guid,
+ cancellable, flags));
}
Glib::RefPtr<Server> Server::create_sync(const std::string& address,
@@ -140,48 +105,15 @@ Glib::RefPtr<Server> Server::create_sync(const std::string& address,
const Glib::RefPtr<AuthObserver>& observer,
ServerFlags flags)
{
- //TODO: Use the constructor instead of the code underneath when
- //g_dbus_server_new_sync() does not do more than call g_initable_new().
- //https://bugzilla.gnome.org/show_bug.cgi?id=639478
- //return Glib::RefPtr<Server>(new Server(address, guid, observer,
- //flags));
-
- GError* gerror = 0;
-
- Glib::RefPtr<Server> result =
- Glib::wrap(g_dbus_server_new_sync(address.c_str(),
- static_cast<GDBusServerFlags>(flags),
- guid.c_str(),
- Glib::unwrap(observer),
- 0,
- &gerror));
-
- if(gerror)
- ::Glib::Error::throw_exception(gerror);
-
- return result;
+ return Glib::RefPtr<Server>(new Server(address, guid, observer,
+ flags));
}
Glib::RefPtr<Server> Server::create_sync(const std::string& address,
const std::string& guid,
ServerFlags flags)
{
- //TODO: Use the constructor instead of the code underneath when
- //g_dbus_server_new_sync() does not do more than call g_initable_new().
- //https://bugzilla.gnome.org/show_bug.cgi?id=639478
- //return Glib::RefPtr<Server>(new Server(address, guid, flags));
-
- GError* gerror = 0;
-
- Glib::RefPtr<Server> result =
- Glib::wrap(g_dbus_server_new_sync(address.c_str(),
- static_cast<GDBusServerFlags>(flags),
- guid.c_str(), 0, 0, &gerror));
-
- if(gerror)
- ::Glib::Error::throw_exception(gerror);
-
- return result;
+ return Glib::RefPtr<Server>(new Server(address, guid, flags));
}
} // namespace DBus
diff --git a/gio/src/inputstream.hg b/gio/src/inputstream.hg
index acfb9d3..ba55fa2 100644
--- a/gio/src/inputstream.hg
+++ b/gio/src/inputstream.hg
@@ -64,13 +64,60 @@ public:
_WRAP_METHOD(Glib::RefPtr<Glib::Bytes> read_bytes(gsize count, const Glib::RefPtr<Cancellable>& cancellable), g_input_stream_read_bytes, errthrow)
- //TODO: Documentation.
- /**
+ //TODO: Why not use _WRAP_METHOD() for this?
+ /** Request an asynchronous read of @a count bytes from the stream into a
+ * new Glib::Bytes. When the operation is finished @a slot will be called.
+ * You can then call read_bytes_finish() to get the result of the
+ * operation.
+ *
+ * During an async request no other sync and async calls are allowed, and will
+ * result in Gio::Error with PENDING being thrown.
+ *
+ * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown.
+ *
+ * On success, the new Glib::Bytes will be passed to the callback. It is
+ * not an error if this is smaller than the requested size, as it can
+ * happen e.g. near the end of a file, but generally we try to read as
+ * many bytes as requested. Zero is returned on end of file (or if
+ * @a count is zero), but never otherwise.
+ *
+ * Any outstanding I/O request with higher priority (lower numerical
+ * value) will be executed before an outstanding request with lower
+ * priority. The default priority is PRIORITY_DEFAULT.
+ *
+ * @param count The number of bytes that will be read from the stream.
+ * @param slot Callback to call when the request is satisfied.
+ * @param cancellable A Cancellable object.
+ * @param io_priority The I/O priority of the request.
+ *
* @newin{2,34}
*/
void read_bytes_async(gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
- /**
+ /** Request an asynchronous read of @a count bytes from the stream into a
+ * new Glib::Bytes. When the operation is finished @a slot will be called.
+ * You can then call read_bytes_finish() to get the result of the
+ * operation.
+ *
+ * During an async request no other sync and async calls are allowed, and will
+ * result in Gio::Error with PENDING being thrown.
+ *
+ * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown.
+ *
+ * On success, the new Glib::Bytes will be passed to the callback. It is
+ * not an error if this is smaller than the requested size, as it can
+ * happen e.g. near the end of a file, but generally we try to read as
+ * many bytes as requested. Zero is returned on end of file (or if
+ * @a count is zero), but never otherwise.
+ *
+ * Any outstanding I/O request with higher priority (lower numerical
+ * value) will be executed before an outstanding request with lower
+ * priority. The default priority is PRIORITY_DEFAULT.
+ *
+ * @param count The number of bytes that will be read from the stream.
+ * @param slot Callback to call when the request is satisfied.h
+ * @param io_priority The I/O priority of the request.
+ *
* @newin{2,34}
*/
void read_bytes_async(gsize count, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT);
@@ -117,7 +164,7 @@ public:
* @param count The number of bytes that will be read from the stream.
* @param slot Callback to call when the request is satisfied.
* @param cancellable A Cancellable object.
- * @param io_priority The I/O priority of the request.
+ * @param io_priority The I/O priority of the request.
*/
void read_async(void* buffer, gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
diff --git a/gio/src/menu.hg b/gio/src/menu.hg
index 0f52734..d6e05e4 100644
--- a/gio/src/menu.hg
+++ b/gio/src/menu.hg
@@ -24,7 +24,14 @@ _PINCLUDE(giomm/private/menumodel_p.h)
namespace Gio
{
-/** TODO
+/** A simple implementation of GMenuModel.
+ * You populate a Menu by adding MenuItem instances to it.
+ *
+ * There are some convenience methods to allow you to directly
+ * add items (avoiding MenuItem) for the common cases. To add
+ * a regular item, use insert(). To add a section, use
+ * insert_section(). To add a submenu, use
+ * insert_submenu().
*
* @newin{2,32}
*/
diff --git a/gio/src/menuitem.hg b/gio/src/menuitem.hg
index 04bf068..51e5e84 100644
--- a/gio/src/menuitem.hg
+++ b/gio/src/menuitem.hg
@@ -24,7 +24,7 @@ _PINCLUDE(glibmm/private/object_p.h)
namespace Gio
{
-/** TODO
+/** A menu item for use with Gio::Menu.
*
* @newin{2,32}
*/
@@ -64,9 +64,13 @@ public:
// Ignore varargs function.
_IGNORE(g_menu_item_get_attribute)
- //TODO: Documentation:
+ //TODO: Rename this to unset_action_target() and deprecate this one.
+ /** Unsets the target for the specified @a action.
+ */
void set_action_and_target(const Glib::ustring& action);
+ //TODO: Add unset_action_and_target().
+
_WRAP_METHOD(void set_action_and_target(const Glib::ustring& action, const Glib::VariantBase& target_value), g_menu_item_set_action_and_target_value)
_IGNORE(g_menu_item_set_action_and_target)
_WRAP_METHOD(void set_detailed_action(const Glib::ustring& detailed_action), g_menu_item_set_detailed_action)
diff --git a/gio/src/outputstream.hg b/gio/src/outputstream.hg
index bcda7c9..fbfc6f1 100644
--- a/gio/src/outputstream.hg
+++ b/gio/src/outputstream.hg
@@ -128,13 +128,71 @@ public:
_WRAP_METHOD(gssize write_bytes(const Glib::RefPtr<const Glib::Bytes>& bytes, const Glib::RefPtr<Cancellable>& cancellable{?}), g_output_stream_write_bytes, errthrow)
- //TODO: Documentation.
- /**
+ /** Request an asynchronous write of the data in @a bytes to the stream.
+ * When the operation is finished @a slot will be called. You can
+ * then call write_bytes_finish() to get the result of
+ * the operation.
+ *
+ * During an async request no other sync and async calls are allowed,
+ * and will result in Gio::Error with PENDING being thrown.
+ *
+ * A Glib:Bytes larger than MAXSSIZE will cause a Gio::Error with
+ * INVALID_ARGUMENT to be thrown.
+ *
+ * On success, the number of bytes written will be passed to the
+ * callback @a slot. It is not an error if this is not the same as the
+ * requested size, as it can happen e.g. on a partial I/O error,
+ * but generally we try to write as many bytes as requested.
+ *
+ * You are guaranteed that this method will never fail with
+ * IO_ERROR_WOULD_BLOCK - if the stream can't accept more data, the
+ * method will just wait until this changes.
+ *
+ * Any outstanding I/O request with higher priority (lower numerical
+ * value) will be executed before an outstanding request with lower
+ * priority. Default priority is Glib::PRIORITY_DEFAULT.
+ *
+ * For the synchronous, blocking version of this function, see write_bytes().
+ *
+ * @param bytes The bytes to
+ * @param slot Callback slot to call when the request is satisfied.
+ * @param cancellable Cancellable object.
+ * @param io_priority The io priority of the request.
+ *
* @newin{2,34}
*/
void write_bytes_async(const Glib::RefPtr<const Glib::Bytes>& bytes, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
- /**
+ /** Request an asynchronous write of the data in @a bytes to the stream.
+ * When the operation is finished @a slot will be called. You can
+ * then call write_bytes_finish() to get the result of
+ * the operation.
+ *
+ * During an async request no other sync and async calls are allowed,
+ * and will result in Gio::Error with PENDING being thrown.
+ *
+ * A Glib:Bytes larger than MAXSSIZE will cause a Gio::Error with
+ * INVALID_ARGUMENT to be thrown.
+ *
+ * On success, the number of bytes written will be passed to the
+ * callback @a slot. It is not an error if this is not the same as the
+ * requested size, as it can happen e.g. on a partial I/O error,
+ * but generally we try to write as many bytes as requested.
+ *
+ * You are guaranteed that this method will never fail with
+ * IO_ERROR_WOULD_BLOCK - if the stream can't accept more data, the
+ * method will just wait until this changes.
+ *
+ * Any outstanding I/O request with higher priority (lower numerical
+ * value) will be executed before an outstanding request with lower
+ * priority. Default priority is Glib::PRIORITY_DEFAULT.
+ *
+ * For the synchronous, blocking version of this function, see write_bytes().
+ *
+ * @param bytes The bytes to
+ * @param slot Callback slot to call when the request is satisfied.
+ * @param io_priority The io priority of the request.
+ *
* @newin{2,34}
*/
void write_bytes_async(const Glib::RefPtr<const Glib::Bytes>& bytes, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT);
@@ -179,7 +237,7 @@ public:
* and will result in Gio::Error with PENDING being thrown.
*
* A value of @a count larger than MAXSSIZE will cause a Gio::Error with
- * NVALID_ARGUMENT to be thrown.
+ * INVALID_ARGUMENT to be thrown.
*
* On success, the number of bytes written will be passed to the
* callback @a slot. It is not an error if this is not the same as the
diff --git a/glib/src/threads.hg b/glib/src/threads.hg
index 89b8131..10ef5dd 100644
--- a/glib/src/threads.hg
+++ b/glib/src/threads.hg
@@ -234,7 +234,12 @@ private:
*/
Mutex* wrap(GMutex* gobject);
-//TODO: Documentation
+/** This represents a recursive mutex.
+ * It is similar to a Mutex with the difference
+ * that it is possible to lock a RecMutex multiple times in the same
+ * thread without deadlock. When doing so, care has to be taken to
+ * unlock the recursive mutex as often as it has been locked.
+ */
class RecMutex
{
public:
@@ -296,7 +301,17 @@ private:
*/
RecMutex* wrap(GRecMutex* gobject);
-//TODO: Documentation
+/** This represents a reader-writer lock.
+ * It is similar to a Mutex in that it allows
+ * multiple threads to coordinate access to a shared resource.
+ *
+ * The difference to a mutex is that a reader-writer lock discriminates
+ * between read-only ('reader') and full ('writer') access. While only
+ * one thread at a time is allowed write access (by holding the 'writer'
+ * lock via writer_lock()), multiple threads can gain
+ * simultaneous read-only access (by holding the 'reader' lock via
+ * reader_lock()).
+ */
class RWLock
{
public:
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
