GNOME.org
 

[geocode-glib] lib: Update API docs

commit c8a481018c2523ec450b405ba1f578d19b6cdf4d
Author: Bastien Nocera <hadess hadess net>
Date:   Sun Nov 25 18:24:22 2012 +0100

    lib: Update API docs

 TODO                            |    1 -
 geocode-glib/geocode-forward.c  |   28 ++++++++++++----------------
 geocode-glib/geocode-forward.h  |    7 +++++++
 geocode-glib/geocode-glib.c     |    4 ++--
 geocode-glib/geocode-location.c |   32 ++++++++++++++++++++++++++++++++
 geocode-glib/geocode-location.h |   16 ++++++++++++++--
 geocode-glib/geocode-reverse.c  |   32 ++++++++++++++------------------
 geocode-glib/geocode-reverse.h  |    7 +++++++
 8 files changed, 88 insertions(+), 39 deletions(-)
---
diff --git a/TODO b/TODO
index 8df26ef..967acd3 100644
--- a/TODO
+++ b/TODO
@@ -1,5 +1,4 @@
 - More test cases
-- Finish API docs
 - Write examples
 
 - Make geocode_foward_new_for_params() output warnings if a key is unknown to us
diff --git a/geocode-glib/geocode-forward.c b/geocode-glib/geocode-forward.c
index d2276e1..c670d48 100644
--- a/geocode-glib/geocode-forward.c
+++ b/geocode-glib/geocode-forward.c
@@ -210,7 +210,7 @@ geocode_forward_new_for_params (GHashTable *params)
  * geocode_forward_new_for_string:
  * @str: a string containing a free-form description of the location
  *
- * Creates a new #GeocodeForward to perform geocoding with. The
+ * Creates a new #GeocodeForward to perform forward geocoding with. The
  * string is in free-form format.
  *
  * Returns: a new #GeocodeForward. Use g_object_unref() when done.
@@ -228,17 +228,6 @@ geocode_forward_new_for_string (const char *location)
 	return forward;
 }
 
-/**
- * geocode_forward_add:
- * @forward: a #GeocodeForward
- * @key: a string representing a parameter to the web service
- * @value: a string representing the value of a parameter
- *
- * Adds parameters to the geocoding or reverse geocoding request.
- * A copy of the key and value parameters are kept internally.
- *
- * This function is mainly intended for language bindings.
- **/
 static void
 geocode_forward_add (GeocodeForward *forward,
 		     const char    *key,
@@ -404,7 +393,7 @@ get_search_query_for_params (GeocodeForward *forward,
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
  * @user_data: the data to pass to callback function
  *
- * Asynchronously gets a list of a geocoding
+ * Asynchronously performs a forward geocoding
  * query using a web service. Use geocode_forward_search() to do the same
  * thing synchronously.
  *
@@ -412,7 +401,7 @@ get_search_query_for_params (GeocodeForward *forward,
  * geocode_forward_search_finish() to get the result of the operation.
  **/
 void
-geocode_forward_search_async (GeocodeForward       *forward,
+geocode_forward_search_async (GeocodeForward      *forward,
 			      GCancellable        *cancellable,
 			      GAsyncReadyCallback  callback,
 			      gpointer             user_data)
@@ -469,7 +458,7 @@ geocode_forward_search_async (GeocodeForward       *forward,
  * @res: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a query operation. See geocode_forward_search_async().
+ * Finishes a forward geocoding operation. See geocode_forward_search_async().
  *
  * Returns: (element-type GHashTable) (transfer full):
  * a #GHashTable containing the results of the query
@@ -656,7 +645,7 @@ parse:
  * @forward: a #GeocodeForward representing a query
  * @error: a #GError
  *
- * Gets the result of a geocoding or reverse geocoding
+ * Gets the result of a forward geocoding
  * query using a web service.
  *
  * Returns: (element-type GHashTable) (transfer full):
@@ -712,6 +701,13 @@ geocode_forward_search (GeocodeForward      *forward,
 	return ret;
 }
 
+/**
+ * geocode_forward_set_answer_count:
+ * @forward: a #GeocodeForward representing a query
+ * @count: the number of requested results
+ *
+ * Sets the number of requested results to @count.
+ **/
 void
 geocode_forward_set_answer_count (GeocodeForward *forward,
 				  guint           count)
diff --git a/geocode-glib/geocode-forward.h b/geocode-glib/geocode-forward.h
index b25dd77..62e07cc 100644
--- a/geocode-glib/geocode-forward.h
+++ b/geocode-glib/geocode-forward.h
@@ -48,11 +48,18 @@ typedef struct _GeocodeForwardClass   GeocodeForwardClass;
 typedef struct _GeocodeForwardPrivate GeocodeForwardPrivate;
 
 struct _GeocodeForward {
+	/* <private> */
 	GObject parent_instance;
 	GeocodeForwardPrivate *priv;
 };
 
+/**
+ * GeocodeForwardClass:
+ *
+ * All the fields in the #GeocodeForwardClass structure are private and should never be accessed directly.
+**/
 struct _GeocodeForwardClass {
+	/* <private> */
 	GObjectClass parent_class;
 };
 
diff --git a/geocode-glib/geocode-glib.c b/geocode-glib/geocode-glib.c
index 441c9b4..83c828a 100644
--- a/geocode-glib/geocode-glib.c
+++ b/geocode-glib/geocode-glib.c
@@ -37,9 +37,9 @@
  *
  * Contains functions for geocoding and reverse geocoding using the
  * <ulink url="http://developer.yahoo.com/geo/placefinder/guide/requests.html";>Yahoo! Place Finder APIs</ulink>
- * for geocoding and reverse geocoding, and the
+ * for reverse geocoding, and the
  * <ulink url="http://developer.yahoo.com/geo/geoplanet/";>Yahoo! GeoPlanet APIs</ulink>
- * for forward geocoding searches.
+ * for forward geocoding.
  **/
 
 char *
diff --git a/geocode-glib/geocode-location.c b/geocode-glib/geocode-location.c
index 96ea31e..b5a5ab4 100644
--- a/geocode-glib/geocode-location.c
+++ b/geocode-glib/geocode-location.c
@@ -22,6 +22,13 @@
 
 #include <geocode-location.h>
 
+/**
+ * SECTION:geocode-location
+ * @short_description: Geocode location object
+ * @include: geocode-glib/geocode-glib.h
+ *
+ * An object representing a location, with optional description.
+ **/
 static gpointer
 geocode_location_copy (gpointer boxed)
 {
@@ -37,6 +44,12 @@ geocode_location_copy (gpointer boxed)
 	return to;
 }
 
+/**
+ * geocode_location_free:
+ * @loc: a #GeocodeLocation object
+ *
+ * Frees a #GeocodeLocation object.
+ **/
 void
 geocode_location_free (GeocodeLocation *loc)
 {
@@ -46,6 +59,15 @@ geocode_location_free (GeocodeLocation *loc)
 
 G_DEFINE_BOXED_TYPE(GeocodeLocation, geocode_location, geocode_location_copy, geocode_location_free)
 
+/**
+ * geocode_location_new:
+ * @latitude: a valid latitude
+ * @longitude: a valid longitude
+ *
+ * Creates a new #GeocodeLocation object.
+ *
+ * Returns: a new #GeocodeLocation object. Use geocode_location_free() when done.
+ **/
 GeocodeLocation *
 geocode_location_new (gdouble latitude,
 		      gdouble longitude)
@@ -62,6 +84,16 @@ geocode_location_new (gdouble latitude,
 	return ret;
 }
 
+/**
+ * geocode_location_new_with_description:
+ * @latitude: a valid latitude
+ * @longitude: a valid longitude
+ * @description: a description for the location
+ *
+ * Creates a new #GeocodeLocation object.
+ *
+ * Returns: a new #GeocodeLocation object. Use geocode_location_free() when done.
+ **/
 GeocodeLocation *
 geocode_location_new_with_description (gdouble     latitude,
 				       gdouble     longitude,
diff --git a/geocode-glib/geocode-location.h b/geocode-glib/geocode-location.h
index ebdb6b1..0f441bf 100644
--- a/geocode-glib/geocode-location.h
+++ b/geocode-glib/geocode-location.h
@@ -27,12 +27,24 @@
 
 G_BEGIN_DECLS
 
-typedef struct {
+typedef struct _GeocodeLocation GeocodeLocation;
+
+/**
+ * GeocodeLocation:
+ * @longitude: a longitude, in degrees
+ * @latitude: a latitude, in degrees
+ * @timestamp: a timestamp in seconds since Epoch.
+ * @description: a description for display
+ *
+ * The #GeocodeLocation structure represents a location
+ * on earth, with an optional description.
+ **/
+struct _GeocodeLocation {
 	gdouble longitude;
 	gdouble latitude;
 	gint64  timestamp;
 	char   *description;
-} GeocodeLocation;
+};
 
 #define GEOCODE_TYPE_LOCATION (geocode_location_get_type ())
 
diff --git a/geocode-glib/geocode-reverse.c b/geocode-glib/geocode-reverse.c
index 64cf5be..a726054 100644
--- a/geocode-glib/geocode-reverse.c
+++ b/geocode-glib/geocode-reverse.c
@@ -33,14 +33,11 @@
 
 /**
  * SECTION:geocode-reverse
- * @short_description: Geocode glib main functions
+ * @short_description: Geocode reverse geocoding object
  * @include: geocode-glib/geocode-glib.h
  *
- * Contains functions for geocoding and reverse geocoding using the
- * <ulink url="http://developer.yahoo.com/geo/placefinder/guide/requests.html";>Yahoo! Place Finder APIs</ulink>
- * for geocoding and reverse geocoding, and the
- * <ulink url="http://developer.yahoo.com/geo/geoplanet/";>Yahoo! GeoPlanet APIs</ulink>
- * for forward geocoding searches.
+ * Contains functions for reverse geocoding using the
+ * <ulink url="http://developer.yahoo.com/geo/placefinder/guide/requests.html";>Yahoo! Place Finder APIs</ulink>.
  **/
 
 struct _GeocodeReversePrivate {
@@ -79,9 +76,8 @@ geocode_reverse_init (GeocodeReverse *object)
 }
 
 /**
- * geocode_reverse_new_for_coords:
- * @latitude: a valid latitude
- * @longitude: a valid longitude
+ * geocode_reverse_new_for_location:
+ * @location: a #GeocodeLocation object
  *
  * Creates a new #GeocodeReverse to perform reverse geocoding with.
  * Use geocode_reverse_resolve_async() to perform the resolution.
@@ -409,7 +405,7 @@ _get_resolve_query_for_params (GHashTable  *orig_ht,
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
  * @user_data: the data to pass to callback function
  *
- * Asynchronously gets the result of a geocoding or reverse geocoding
+ * Asynchronously gets the result of a reverse geocoding
  * query using a web service. Use geocode_reverse_resolve() to do the same
  * thing synchronously.
  *
@@ -418,9 +414,9 @@ _get_resolve_query_for_params (GHashTable  *orig_ht,
  **/
 void
 geocode_reverse_resolve_async (GeocodeReverse       *object,
-			      GCancellable        *cancellable,
-			      GAsyncReadyCallback  callback,
-			      gpointer             user_data)
+			       GCancellable        *cancellable,
+			       GAsyncReadyCallback  callback,
+			       gpointer             user_data)
 {
 	GSimpleAsyncResult *simple;
 	GFile *query;
@@ -469,7 +465,7 @@ geocode_reverse_resolve_async (GeocodeReverse       *object,
  * @res: a #GAsyncResult.
  * @error: a #GError.
  *
- * Finishes a query operation. See geocode_reverse_resolve_async().
+ * Finishes a reverse geocoding operation. See geocode_reverse_resolve_async().
  *
  * Returns: (element-type utf8 utf8) (transfer full):
  * a #GHashTable containing the results of the query
@@ -478,8 +474,8 @@ geocode_reverse_resolve_async (GeocodeReverse       *object,
  **/
 GHashTable *
 geocode_reverse_resolve_finish (GeocodeReverse       *object,
-			       GAsyncResult        *res,
-			       GError             **error)
+				GAsyncResult        *res,
+				GError             **error)
 {
 	GSimpleAsyncResult *simple = G_SIMPLE_ASYNC_RESULT (res);
 	GHashTable *ret;
@@ -504,7 +500,7 @@ out:
  * @object: a #GeocodeReverse representing a query
  * @error: a #GError
  *
- * Gets the result of a geocoding or reverse geocoding
+ * Gets the result of a reverse geocoding
  * query using a web service.
  *
  * Returns: (element-type utf8 utf8) (transfer full):
@@ -513,7 +509,7 @@ out:
  * Free the returned string with g_hash_table_destroy() when done.
  **/
 GHashTable *
-geocode_reverse_resolve (GeocodeReverse       *object,
+geocode_reverse_resolve (GeocodeReverse      *object,
 			 GError             **error)
 {
 	GFile *query;
diff --git a/geocode-glib/geocode-reverse.h b/geocode-glib/geocode-reverse.h
index 7d8b36c..5e7d688 100644
--- a/geocode-glib/geocode-reverse.h
+++ b/geocode-glib/geocode-reverse.h
@@ -47,11 +47,18 @@ typedef struct _GeocodeReverseClass   GeocodeReverseClass;
 typedef struct _GeocodeReversePrivate GeocodeReversePrivate;
 
 struct _GeocodeReverse {
+	/* <private> */
 	GObject parent_instance;
 	GeocodeReversePrivate *priv;
 };
 
+/**
+ * GeocodeReverseClass:
+ *
+ * All the fields in the #GeocodeReverseClass structure are private and should never be accessed directly.
+**/
 struct _GeocodeReverseClass {
+	/* <private> */
 	GObjectClass parent_class;
 };
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]