Created attachment 297119 [details] [review]
docs: Expand introduction to mention using async calls over sync ones

As discussed on the mailing list (see the whole thread):
    https://mail.gnome.org/archives/desktop-devel-list/2015-February/msg00126.html

Expand the GIO documentation introduction to talk a little about when to
use async and sync functions, and how the former should almost always be
preferred over the latter.

Link to this from the GFile documentation, which is an entry point for a
lot of async calls.

Review of attachment 297119 [details] [review]:

One minor comment below, but otherwise it looks quite good.

::: docs/reference/gio/overview.xml
@@ +195,3 @@
+    <para>
+      Many GIO functions come in two versions: synchronous and asynchronous,
+      denoted by an <code>_async</code> suffix. It is important to use these

Might be worth mentioning that we have a bunch of APIs that work the davidz way: _sync() for the sync version and no suffix for the async one.

Pushed with a short paragraph inserted to mention the _sync variants.

Related report which needs review: bug #745092.

Attachment 297119 [details] pushed as 4308149 - docs: Expand introduction to mention using async calls over sync ones