[glibmm/glibmm-2-62] Gio::AsyncResult: Improve the class description

[Kjell Ahlstedt <kjellahl src gnome org>]

commit edb8902852a6983885101dbbe547378007779495
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Fri Dec 20 16:53:14 2019 +0100

    Gio::AsyncResult: Improve the class description
    
    Fixes #27

 gio/src/asyncresult.hg | 77 +++++++++++++++++++++++++++++---------------------
 1 file changed, 45 insertions(+), 32 deletions(-)
---
diff --git a/gio/src/asyncresult.hg b/gio/src/asyncresult.hg
index 4c4da93c..7472dc6f 100644
--- a/gio/src/asyncresult.hg
+++ b/gio/src/asyncresult.hg
@@ -36,63 +36,76 @@ class AsyncResult;
  *
  * For instance,
  * @code
- * void on_async_ready(Glib::RefPtr<AsyncResult>& result);
+ * void on_async_ready(Glib::RefPtr<Gio::AsyncResult>& result);
  * @endcode
  *
  * @newin{2,16}
+ * @relates Gio::AsyncResult
  */
 using SlotAsyncReady = sigc::slot<void, Glib::RefPtr<AsyncResult>&>;
 
 /** Provides a base class for implementing asynchronous function results.
+ *
  * Asynchronous operations are broken up into two separate operations which are chained together by a 
SlotAsyncReady.
  * To begin an asynchronous operation, provide a SlotAsyncReady to the asynchronous function. This callback 
will be triggered
- * when the operation has completed, and will be passed an AsyncResult instance filled with the details of 
the operation's success or
- * failure, the object the asynchronous function was started for and any error codes returned. The 
asynchronous callback function is then
- * expected to call the corresponding "_finish()" function with the object the function was called for, and 
the AsyncResult instance.
+ * when the operation has completed, and will be passed an %AsyncResult instance
+ * (an instance of a class that implements the %AsyncResult interface)
+ * filled with the details of the operation's success or failure,
+ * the object the asynchronous function was started for and any error codes returned. The asynchronous 
callback function is then
+ * expected to call the corresponding "_finish()" function of the object the async function was called for, 
with the %AsyncResult instance.
  *
- * The purpose of the "_finish()" function is to take the generic result of type AsyncResult and return the 
specific result that the operation
+ * The purpose of the "_finish()" function is to take the generic result of type %AsyncResult and return the 
specific result that the operation
  * in question yields (e.g. a FileEnumerator for an "enumerate children" operation). If the result or error 
status of the operation is not needed,
  * there is no need to call the "_finish()" function and GIO will take care of cleaning up the result and 
error information after the
- * SlotAsyncReady returns. You may also store the AsyncResult and call "_finish()" later.
+ * SlotAsyncReady returns. You may also store the %AsyncResult and call "_finish()" later.
+ * However, the "_finish()" function may be called at most once.
  *
  * Example of a typical asynchronous operation flow:
  * @code
- * void _theoretical_frobnitz_async(const Glib::RefPtr<Theoretical>& t,
- *                                  const SlotAsyncReady& slot);
- *
- * gboolean _theoretical_frobnitz_finish(const Glib::RefPtr<Theoretical>& t,
- *                                       const Glib::RefPtr<AsyncResult>& result);
- *
- * static void
- * on_frobnitz_result(Glib::RefPtr<AsyncResult>& result)
+ * class Theoretical : public Glib::Object
  * {
+ * public:
+ *   Glib::RefPtr<Theoretical> create();
  *
- *   Glib::RefPtr<Glib::Object> source_object = result->get_source_object();
- *   bool success = _theoretical_frobnitz_finish(source_object, res);
+ *   void frobnitz_async(const Gio::SlotAsyncReady& slot);
+ *   Glib::ustring frobnitz_finish(const Glib::RefPtr<Gio::AsyncResult>& result);
+ * // ...
+ * };
  *
- *   if (success)
- *     std::cout << "Hurray" << std::endl;
- *   else
- *     std::cout << "Uh oh!" << std::endl;
- *
- *   ...
- * }
+ * // ...
  *
- * int main (int argc, void *argv[])
+ * namespace
  * {
- *    ...
+ * Glib::RefPtr<Theoretical> theoretical;
  *
- *    _theoretical_frobnitz_async (theoretical_data,
- *                                 sigc::ptr_fun(&on_frobnitz_result) );
+ * void on_frobnitz_ready(Glib::RefPtr<Gio::AsyncResult>& result)
+ * {
+ *   try
+ *   {
+ *     Glib::ustring s = theoretical->frobnitz_finish(result);
+ *     std::cout << s << std::endl;
+ *   }
+ *   catch (const Glib::Error& err)
+ *   {
+ *     std::cerr << err.what() << std::endl;
+ *   }
+ *   // ...
+ * }
+ * } // anonymous namespace
  *
- *    ...
+ * int main(int argc, void* argv[])
+ * {
+ *   // ...
+ *   theoretical = Theoretical::create();
+ *   theoretical->frobnitz_async(sigc::ptr_fun(&on_frobnitz_ready));
+ *   // ...
  * }
  * @endcode
  *
- * The async function could also take an optional Glib::Cancellable object, allowing the calling function to 
cancel the asynchronous operation.
+ * The async function could also take an optional Gio::Cancellable object, allowing the calling function to 
cancel the asynchronous operation.
  *
  * The callback for an asynchronous operation is called only once, and is always called, even in the case of 
a cancelled operation.
- * On cancellation, the result is an <tt>ERROR_CANCELLED</tt> error.
+ * On cancellation the "_finish()" function will throw a Gio::Error exception with a 
<tt>Gio::Error::CANCELLED</tt> error code.
  *
  * @newin{2,16}
  */
@@ -119,8 +132,8 @@ public:
 
   _WRAP_METHOD(bool is_tagged(gpointer source_tag) const, g_async_result_is_tagged)
 
-
-  // TODO: For some reason, the compiler cannot find an unwrap() for ObjectBase.
+  // The compiler cannot find an unwrap() for ObjectBase, because
+  // ObjectBase::BaseObjectType is not declared.
   //#m4 _CONVERSION(`Glib::RefPtr<Glib::ObjectBase>',`GObject*',__CONVERT_REFPTR_TO_P)
 #m4 _CONVERSION(`Glib::RefPtr<Glib::ObjectBase>',`GObject*',`unwrap_objectbase_custom($3)')
   _WRAP_VFUNC(Glib::RefPtr<Glib::ObjectBase> get_source_object(),