Fix developer documentation

Add some missing docs, and fix the section declarations.

5 files changed, 74 insertions, 23 deletions

diff --git a/doc/libgweather-sections.txt b/doc/libgweather-sections.txt
index df00013..19ded17 100644
--- a/doc/libgweather-sections.txt
+++ b/doc/libgweather-sections.txt
@@ -4,11 +4,11 @@
 <FILE>gweathertimezonemenu</FILE>
 <TITLE>GWeatherTimezoneMenu</TITLE>
 GWeatherTimezoneMenu
-GWeatherTimezoneMenuClass
 gweather_timezone_menu_new
 gweather_timezone_menu_set_tzid
 gweather_timezone_menu_get_tzid
 <SUBSECTION Standard>
+GWeatherTimezoneMenuClass
 GWEATHER_TIMEZONE_MENU
 GWEATHER_IS_TIMEZONE_MENU
 GWEATHER_TYPE_TIMEZONE_MENU
@@ -22,13 +22,13 @@ GWEATHER_TIMEZONE_MENU_GET_CLASS
 <FILE>gweatherlocationentry</FILE>
 <TITLE>GWeatherLocationEntry</TITLE>
 GWeatherLocationEntry
-GWeatherLocationEntryClass
 gweather_location_entry_new
 gweather_location_entry_set_location
 gweather_location_entry_get_location
 gweather_location_entry_has_custom_text
 gweather_location_entry_set_city
 <SUBSECTION Standard>
+GWeatherLocationEntryClass
 GWEATHER_LOCATION_ENTRY
 GWEATHER_IS_LOCATION_ENTRY
 GWEATHER_TYPE_LOCATION_ENTRY
@@ -36,6 +36,7 @@ gweather_location_entry_get_type
 GWEATHER_LOCATION_ENTRY_CLASS
 GWEATHER_IS_LOCATION_ENTRY_CLASS
 GWEATHER_LOCATION_ENTRY_GET_CLASS
+GWeatherLocationEntryPrivate
 </SECTION>
 
 <SECTION>
@@ -104,6 +105,7 @@ gweather_info_update
 gweather_info_abort
 gweather_info_is_valid
 gweather_info_network_error
+gweather_info_store_cache
 gweather_info_get_location
 gweather_info_set_location
 gweather_info_get_forecast_list
@@ -117,6 +119,7 @@ gweather_info_get_attribution
 <SUBSECTION>
 gweather_info_get_location_name
 gweather_info_get_icon_name
+gweather_info_get_symbolic_icon_name
 gweather_info_get_weather_summary
 gweather_info_get_temp_summary
 gweather_info_get_update
@@ -169,6 +172,7 @@ gweather_info_get_value_sunset
 gweather_info_next_sun_event
 gweather_info_get_value_moonphase
 gweather_info_get_upcoming_moonphases
+gweather_info_is_daytime
 </SECTION>
 
 <SECTION>
diff --git a/libgweather/gweather-location.c b/libgweather/gweather-location.c
index 21d1b20..ee5a694 100644
--- a/libgweather/gweather-location.c
+++ b/libgweather/gweather-location.c
@@ -38,7 +38,7 @@
 #define EPSILON 0.000001
 
 /**
- * SECTION:gweather-location
+ * SECTION:gweatherlocation
  * @Title: GWeatherLocation
  *
  * A #GWeatherLocation represents a "location" of some type known to
@@ -1043,20 +1043,43 @@ gweather_location_format_one_deserialize (GWeatherLocation *world,
 
 /**
  * gweather_location_serialize:
- * @location: a #GWeatherLocation
+ * @loc: a city, weather station or detached #GWeatherLocation
  *
- * Returns: (transfer none):
+ * Transforms a #GWeatherLocation into a #GVariant, in a way that
+ * calling gweather_location_deserialize() will hold an equivalent
+ * #GWeatherLocation.
+ * The resulting variant can then be stored into GSettings or on disk.
+ * This call is only valid for cities, weather stations and detached
+ * locations.
+ * The format of the resulting #GVariant is private to libgweather,
+ * and it is subject to change. You should use the "v" format in GSettings,
+ * to ensure maximum compatibility with future versions of the library.
+ *
+ * Returns: (transfer none): the serialization of @location.
  */
 GVariant *
-gweather_location_serialize (GWeatherLocation *location)
+gweather_location_serialize (GWeatherLocation *loc)
 {
-    g_return_val_if_fail (location != NULL, NULL);
-    g_return_val_if_fail (location->level >= GWEATHER_LOCATION_CITY, NULL);
+    g_return_val_if_fail (loc != NULL, NULL);
+    g_return_val_if_fail (loc->level >= GWEATHER_LOCATION_CITY, NULL);
 
     return g_variant_new ("(uv)", FORMAT,
-			  gweather_location_format_one_serialize (location));
+			  gweather_location_format_one_serialize (loc));
 }
 
+/**
+ * gweather_location_deserialize:
+ * @world: a world-level #GWeatherLocation
+ * @serialized: the #GVariant representing the #GWeatherLocation
+ *
+ * This call undoes the effect of gweather_location_serialize(), that
+ * is, it turns a #GVariant into a #GWeatherLocation. The conversion
+ * happens in the context of @world (i.e, for a city or weather station,
+ * the resulting location will be attached to a administrative division,
+ * country and region as appropriate).
+ *
+ * Returns: (transfer full): the deserialized location.
+ */
 GWeatherLocation *
 gweather_location_deserialize (GWeatherLocation *world,
 			       GVariant         *serialized)
diff --git a/libgweather/timezone-menu.c b/libgweather/timezone-menu.c
index 01a7045..a38bb7d 100644
--- a/libgweather/timezone-menu.c
+++ b/libgweather/timezone-menu.c
@@ -29,7 +29,7 @@
 #include <string.h>
 
 /**
- * SECTION:gtimezonemenu
+ * SECTION:gweathertimezonemenu
  * @Title: GWeatherTimezoneMenu
  *
  * A #GtkComboBox subclass for choosing a #GWeatherTimezone
diff --git a/libgweather/timezone-menu.h b/libgweather/timezone-menu.h
index 15e176c..378c3c2 100644
--- a/libgweather/timezone-menu.h
+++ b/libgweather/timezone-menu.h
@@ -24,6 +24,9 @@
 #include <gtk/gtk.h>
 #include <libgweather/gweather-location.h>
 
+typedef struct _GWeatherTimezoneMenu GWeatherTimezoneMenu;
+typedef struct _GWeatherTimezoneMenuClass GWeatherTimezoneMenuClass;
+
 #define GWEATHER_TYPE_TIMEZONE_MENU            (gweather_timezone_menu_get_type ())
 #define GWEATHER_TIMEZONE_MENU(object)         (G_TYPE_CHECK_INSTANCE_CAST ((object), GWEATHER_TYPE_TIMEZONE_MENU, GWeatherTimezoneMenu))
 #define GWEATHER_TIMEZONE_MENU_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GWEATHER_TYPE_TIMEZONE_MENU, GWeatherTimezoneMenuClass))
@@ -31,17 +34,17 @@
 #define GWEATHER_IS_TIMEZONE_MENU_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GWEATHER_TYPE_TIMEZONE_MENU))
 #define GWEATHER_TIMEZONE_MENU_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GWEATHER_TYPE_TIMEZONE_MENU, GWeatherTimezoneMenuClass))
 
-typedef struct {
+struct _GWeatherTimezoneMenu {
     GtkComboBox parent;
 
     /*< private >*/
     GWeatherTimezone *zone;
-} GWeatherTimezoneMenu;
+};
 
-typedef struct {
+struct _GWeatherTimezoneMenuClass {
     GtkComboBoxClass parent_class;
 
-} GWeatherTimezoneMenuClass;
+};
 
 GType       gweather_timezone_menu_get_type         (void);
 
diff --git a/libgweather/weather.c b/libgweather/weather.c
index b36534d..e0cf27f 100644
--- a/libgweather/weather.c
+++ b/libgweather/weather.c
@@ -500,6 +500,17 @@ gweather_info_store_cache (void)
     soup_cache_dump (cache);
 }
 
+/**
+ * gweather_info_update:
+ * @info: a #GWeatherInfo
+ *
+ * Requests a reload of weather conditions and forecast data from
+ * enabled network services.
+ * This call does no synchronous IO: rather, the result is delivered
+ * by emitting the #GWeatherInfo::updated signal.
+ * Note that if no network services are enabled, the signal will not
+ * be emitted. See #GWeatherInfo:enabled-providers for details.
+ */
 void
 gweather_info_update (GWeatherInfo *info)
 {
@@ -1098,13 +1109,13 @@ gweather_info_get_weather_summary (GWeatherInfo *info)
  * gweather_info_is_daytime:
  * @info: a #GWeatherInfo
  *
- * Returns whether it is daytime (that is, if the sun is visible)
- * or not at the location and the point of time referred by @info.
- * This is mostly equivalent to comparing the return value
- * of gweather_info_get_value_sunrise() and
- * gweather_info_get_value_sunset(), but it accounts also
- * for midnight sun and polar night, for locations within
- * the Artic and Antartic circles.
+ * Returns: Whether it is daytime (that is, if the sun is visible)
+ *   or not at the location and the point of time referred by @info.
+ *   This is mostly equivalent to comparing the return value
+ *   of gweather_info_get_value_sunrise() and
+ *   gweather_info_get_value_sunset(), but it accounts also
+ *   for midnight sun and polar night, for locations within
+ *   the Artic and Antartic circles.
  */
 gboolean
 gweather_info_is_daytime (GWeatherInfo *info)
@@ -2043,6 +2054,14 @@ gweather_info_class_init (GWeatherInfoClass *klass)
 				G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE);
     g_object_class_install_property (gobject_class, PROP_ENABLED_PROVIDERS, pspec);
 
+    /**
+     * GWeatherInfo::updated:
+     * @object: the emitter of the signal.
+     *
+     * This signal is emitted after the initial fetch of the weather
+     * data from upstream services, and after every successful call
+     * to @gweather_info_update().
+     */
     gweather_info_signals[SIGNAL_UPDATED] = g_signal_new ("updated",
 							  GWEATHER_TYPE_INFO,
 							  G_SIGNAL_RUN_FIRST,
@@ -2059,8 +2078,10 @@ gweather_info_class_init (GWeatherInfoClass *klass)
  * @forecast_type: the type of forecast requested
  *
  * Builds a new #GWeatherInfo that will provide weather information about
- * @location. The returned info will not be ready until the #GWeatherInfo::updated signal
- * is emitted.
+ * @location.
+ * Note that, as compared to g_object_new(), this will call gweather_info_update()
+ * on the resulting info, which will not be ready until the #GWeatherInfo::updated
+ * signal is emitted.
  *
  * Returns: (transfer full): a new #GWeatherInfo
  */