X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gio%2Fginitable.c;h=23d6069f3b3efd5a41a1d4c531cd1f1fad549ea8;hb=d108ada4b98cb50fb1517f55c4f09acdaf3de471;hp=de59e206f127a4ee8e58123e87f7e9ea522d0cb6;hpb=5b946e0504952a472cea1ef95df0967e8a4a7b47;p=platform%2Fupstream%2Fglib.git

diff --git a/gio/ginitable.c b/gio/ginitable.c
index de59e20..23d6069 100644
--- a/gio/ginitable.c
+++ b/gio/ginitable.c
@@ -13,9 +13,7 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  *
  * Author: Alexander Larsson <alexl@redhat.com>
  */
@@ -32,18 +30,24 @@
  * @see_also: #GAsyncInitable
  *
  * #GInitable is implemented by objects that can fail during
- * initialization. If an object implements this interface the
- * g_initable_init() function must be called as the first thing
- * after construction. If g_initable_init() is not called, or if
- * it returns an error, all further operations on the object
- * should fail, generally with a %G_IO_ERROR_NOT_INITIALIZED error.
+ * initialization. If an object implements this interface then
+ * it must be initialized as the first thing after construction,
+ * either via g_initable_init() or g_async_initable_init_async()
+ * (the latter is only available if it also implements #GAsyncInitable).
+ *
+ * If the object is not initialized, or initialization returns with an
+ * error, then all operations on the object except g_object_ref() and
+ * g_object_unref() are considered to be invalid, and have undefined
+ * behaviour. They will often fail with g_critical() or g_warning(), but
+ * this must not be relied on.
  *
  * Users of objects implementing this are not intended to use
  * the interface method directly, instead it will be used automatically
  * in various ways. For C applications you generally just call
  * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
  * This will call g_initable_init() under the cover, returning %NULL and
- * setting a %GError on failure.
+ * setting a #GError on failure (at which point the instance is
+ * unreferenced).
  *
  * For bindings in languages where the native constructor supports
  * exceptions the binding could check for objects implemention %GInitable
@@ -63,11 +67,13 @@ g_initable_default_init (GInitableInterface *iface)
  * g_initable_init:
  * @initable: a #GInitable.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError location to store the error occuring, or %NULL to
+ * @error: a #GError location to store the error occurring, or %NULL to
  * ignore.
  *
- * Initializes the object implementing the interface. This must be
- * done before any real use of the object after initial construction.
+ * Initializes the object implementing the interface.
+ *
+ * The object must be initialized before any real use after initial
+ * construction, either with this function or g_async_initable_init_async().
  *
  * Implementations may also support cancellation. If @cancellable is not %NULL,
  * then initialization can be cancelled by triggering the cancellable object
@@ -76,14 +82,15 @@ g_initable_default_init (GInitableInterface *iface)
  * the object doesn't support cancellable initialization the error
  * %G_IO_ERROR_NOT_SUPPORTED will be returned.
  *
- * If this function is not called, or returns with an error then all
- * operations on the object should fail, generally returning the
- * error %G_IO_ERROR_NOT_INITIALIZED.
+ * If the object is not initialized, or initialization returns with an
+ * error, then all operations on the object except g_object_ref() and
+ * g_object_unref() are considered to be invalid, and have undefined
+ * behaviour. See the [introduction][ginitable] for more details.
  *
  * Implementations of this method must be idempotent, i.e. multiple calls
  * to this function with the same argument should return the same results.
  * Only the first call initializes the object, further calls return the result
- * of the first call. This is so that its safe to implement the singleton
+ * of the first call. This is so that it's safe to implement the singleton
  * pattern in the GObject constructor function.
  *
  * Returns: %TRUE if successful. If an error has occurred, this function will
@@ -109,18 +116,19 @@ g_initable_init (GInitable     *initable,
  * g_initable_new:
  * @object_type: a #GType supporting #GInitable.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError location to store the error occuring, or %NULL to
+ * @error: a #GError location to store the error occurring, or %NULL to
  *    ignore.
- * @first_property_name: the name of the first property, or %NULL if no
+ * @first_property_name: (allow-none): the name of the first property, or %NULL if no
  *     properties
  * @...:  the value if the first property, followed by and other property
  *    value pairs, and ended by %NULL.
  *
- * Helper function for constructing #GInitiable object. This is
+ * Helper function for constructing #GInitable object. This is
  * similar to g_object_new() but also initializes the object
  * and returns %NULL, setting an error on failure.
  *
- * Return value: a newly allocated #GObject, or %NULL on error
+ * Returns: (type GObject.Object) (transfer full): a newly allocated
+ *      #GObject, or %NULL on error
  *
  * Since: 2.22
  */
@@ -147,16 +155,17 @@ g_initable_new (GType          object_type,
  * g_initable_newv:
  * @object_type: a #GType supporting #GInitable.
  * @n_parameters: the number of parameters in @parameters
- * @parameters: the parameters to use to construct the object
+ * @parameters: (array length=n_parameters): the parameters to use to construct the object
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError location to store the error occuring, or %NULL to
+ * @error: a #GError location to store the error occurring, or %NULL to
  *     ignore.
  *
- * Helper function for constructing #GInitiable object. This is
+ * Helper function for constructing #GInitable object. This is
  * similar to g_object_newv() but also initializes the object
  * and returns %NULL, setting an error on failure.
  *
- * Return value: a newly allocated #GObject, or %NULL on error
+ * Returns: (type GObject.Object) (transfer full): a newly allocated
+ *      #GObject, or %NULL on error
  *
  * Since: 2.22
  */
@@ -189,14 +198,15 @@ g_initable_newv (GType          object_type,
  * the value, and other property value pairs, and ended by %NULL.
  * @var_args: The var args list generated from @first_property_name.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError location to store the error occuring, or %NULL to
+ * @error: a #GError location to store the error occurring, or %NULL to
  *     ignore.
  *
- * Helper function for constructing #GInitiable object. This is
+ * Helper function for constructing #GInitable object. This is
  * similar to g_object_new_valist() but also initializes the object
  * and returns %NULL, setting an error on failure.
  *
- * Return value: a newly allocated #GObject, or %NULL on error
+ * Returns: (type GObject.Object) (transfer full): a newly allocated
+ *      #GObject, or %NULL on error
  *
  * Since: 2.22
  */