GNOME.org
 

[libgweather] Fix docs

commit 2806ddfe56cfeb8a6986c14a0e2732152c184837
Author: Giovanni Campagna <scampa giovanni gmail com>
Date:   Sun Feb 15 21:06:08 2015 -0800

    Fix docs
    
    Add everything to libgweather-sections.txt and add missing
    enum descriptions

 doc/libgweather-sections.txt    |    7 ++-
 libgweather/gweather-enums.h    |   50 +++++++++++++++++
 libgweather/gweather-location.c |    7 ++-
 libgweather/gweather-timezone.c |    7 ++-
 libgweather/gweather-weather.h  |  111 +++++++++++++++++++++++++++++++++++++++
 libgweather/weather.c           |    4 +-
 6 files changed, 177 insertions(+), 9 deletions(-)
---
diff --git a/doc/libgweather-sections.txt b/doc/libgweather-sections.txt
index f5da5c1..63da2fd 100644
--- a/doc/libgweather-sections.txt
+++ b/doc/libgweather-sections.txt
@@ -44,7 +44,6 @@ GWeatherLocationEntryPrivate
 <TITLE>GWeatherLocation</TITLE>
 GWeatherLocation
 GWeatherLocationLevel
-gweather_location_find_nearest_city
 gweather_location_get_world
 gweather_location_new_world
 gweather_location_new_detached
@@ -56,6 +55,11 @@ gweather_location_serialize
 gweather_location_deserialize
 gweather_location_equal
 gweather_location_find_by_station_code
+gweather_location_find_nearest_city
+GWeatherFilterFunc
+gweather_location_find_nearest_city_full
+gweather_location_detect_nearest_city
+gweather_location_detect_nearest_city_finish
 
 <SUBSECTION>
 gweather_location_get_level
@@ -73,6 +77,7 @@ gweather_location_get_timezone
 gweather_location_get_timezones
 gweather_location_get_code
 gweather_location_get_city_name
+gweather_location_get_country_name
 
 <SUBSECTION Private>
 gweather_location_free_timezones
diff --git a/libgweather/gweather-enums.h b/libgweather/gweather-enums.h
index e994a5b..3ce1213 100644
--- a/libgweather/gweather-enums.h
+++ b/libgweather/gweather-enums.h
@@ -21,6 +21,17 @@
 #ifndef __GWEATHER_ENUMS_H_
 #define __GWEATHER_ENUMS_H_
 
+/**
+ * GWeatherTemperatureUnit:
+ * @GWEATHER_TEMP_UNIT_INVALID: invalid unit
+ * @GWEATHER_TEMP_UNIT_DEFAULT: the user preferred temperature unit
+ * @GWEATHER_TEMP_UNIT_KELVIN: Kelvin (absolute) temperature scale
+ * @GWEATHER_TEMP_UNIT_CENTIGRADE: Celsius temperature scale
+ * @GWEATHER_TEMP_UNIT_FAHRENHEIT: Fahrenheit temperature scale
+ *
+ * The measure unit to use for temperature values, when retrieved by
+ * the gweather_info_get_value_temp() family of functions.
+ */
 typedef enum { /*< underscore_name=gweather_temperature_unit >*/
     GWEATHER_TEMP_UNIT_INVALID = 0,
     GWEATHER_TEMP_UNIT_DEFAULT,
@@ -29,6 +40,19 @@ typedef enum { /*< underscore_name=gweather_temperature_unit >*/
     GWEATHER_TEMP_UNIT_FAHRENHEIT
 } GWeatherTemperatureUnit;
 
+/**
+ * GWeatherSpeedUnit:
+ * @GWEATHER_SPEED_UNIT_INVALID: invalid unit
+ * @GWEATHER_SPEED_UNIT_DEFAULT: the user preferred speed unit
+ * @GWEATHER_SPEED_UNIT_MS: meters per second
+ * @GWEATHER_SPEED_UNIT_KPH: kilometers per hour
+ * @GWEATHER_SPEED_UNIT_MPH: miles per hour
+ * @GWEATHER_SPEED_UNIT_KNOTS: knots
+ * @GWEATHER_SPEED_UNIT_BFT: Beaufort scale
+ *
+ * The measure unit to use for wind speed values, when retrieved by
+ * gweather_info_get_value_wind().
+ */
 typedef enum { /*< underscore_name=gweather_speed_unit >*/
     GWEATHER_SPEED_UNIT_INVALID = 0,
     GWEATHER_SPEED_UNIT_DEFAULT,
@@ -39,6 +63,21 @@ typedef enum { /*< underscore_name=gweather_speed_unit >*/
     GWEATHER_SPEED_UNIT_BFT    /* Beaufort scale */
 } GWeatherSpeedUnit;
 
+/**
+ * GWeatherPressureUnit:
+ * @GWEATHER_PRESSURE_UNIT_INVALID: invalid unit
+ * @GWEATHER_PRESSURE_UNIT_DEFAULT: the user preferred pressure unit
+ * @GWEATHER_PRESSURE_UNIT_KPA: kiloPascal (* 10^3 Pa)
+ * @GWEATHER_PRESSURE_UNIT_HPA: hectoPascal (* 10^2 Pa); also known
+ *                              as millibars, but formatted differently
+ * @GWEATHER_PRESSURE_UNIT_MB: millibars; same as %GWEATHER_PRESSURE_UNIT_HPA
+ * @GWEATHER_PRESSURE_UNIT_MM_HG: millimiters of mercury
+ * @GWEATHER_PRESSURE_UNIT_INCH_HG: inches of mercury
+ * @GWEATHER_PRESSURE_UNIT_ATM: atmospheres
+ *
+ * The measure unit to use for atmospheric pressure values, when
+ * retrieved by gweather_info_get_value_pressure().
+ */
 typedef enum { /*< underscore_name=gweather_pressure_unit >*/
     GWEATHER_PRESSURE_UNIT_INVALID = 0,
     GWEATHER_PRESSURE_UNIT_DEFAULT,
@@ -50,6 +89,17 @@ typedef enum { /*< underscore_name=gweather_pressure_unit >*/
     GWEATHER_PRESSURE_UNIT_ATM     /* atmosphere */
 } GWeatherPressureUnit;
 
+/**
+ * GWeatherDistanceUnit:
+ * @GWEATHER_DISTANCE_UNIT_INVALID: invalid unit
+ * @GWEATHER_DISTANCE_UNIT_DEFAULT: the user preferred distance unit
+ * @GWEATHER_DISTANCE_UNIT_METERS: meters
+ * @GWEATHER_DISTANCE_UNIT_KM: kilometers (= 1000 meters)
+ * @GWEATHER_DISTANCE_UNIT_MILES: miles
+ *
+ * The measure unit to use for sky visibility values, when retrieved
+ * by gweather_info_get_value_visibility().
+ */
 typedef enum { /*< underscore_name=gweather_distance_unit >*/
     GWEATHER_DISTANCE_UNIT_INVALID = 0,
     GWEATHER_DISTANCE_UNIT_DEFAULT,
diff --git a/libgweather/gweather-location.c b/libgweather/gweather-location.c
index 43387fb..324b80a 100644
--- a/libgweather/gweather-location.c
+++ b/libgweather/gweather-location.c
@@ -597,7 +597,7 @@ find_nearest_city (GWeatherLocation *location,
  * Finds the nearest city to the passed latitude and
  * longitude, among the descendants of @loc.
  *
- * @loc must be at most a %GWEATHER_LOCATION_LEVEL_ADM2 location.
+ * @loc must be at most a %GWEATHER_LOCATION_ADM2 location.
  * This restriction may be lifted in a future version.
  *
  * Note that this function does not check if (@lat, @lon) fall inside
@@ -652,7 +652,7 @@ gweather_location_find_nearest_city (GWeatherLocation *loc,
  * Supports the use of own filter function to filter out locations.
  * Geocoding should be done on the application side if needed.
  *
- * @loc must be at most a %GWEATHER_LOCATION_LEVEL_ADM2 location.
+ * @loc must be at most a %GWEATHER_LOCATION_ADM2 location.
  * This restriction may be lifted in a future version.
  *
  * Returns: (transfer full): the city closest to (@lat, @lon), in the
@@ -743,11 +743,12 @@ void _got_place (GObject      *source_object,
  * @lon: Longitude, in degrees
  * @cancellable: optional, NULL to ignore
  * @callback: callback function for GAsyncReadyCallback argument for GSimpleAsyncResult
+ * @user_data: user data passed to @callback
  *
  * Initializes geocode reversing to find place for (@lat, @lon) coordinates. Calls the callback
  * function passed by user when the result is ready.
  *
- * @loc must be at most a %GWEATHER_LOCATION_LEVEL_ADM2 location.
+ * @loc must be at most a %GWEATHER_LOCATION_ADM2 location.
  * This restriction may be lifted in a future version.
  *
  * Returns: void
diff --git a/libgweather/gweather-timezone.c b/libgweather/gweather-timezone.c
index fda951a..d2132cd 100644
--- a/libgweather/gweather-timezone.c
+++ b/libgweather/gweather-timezone.c
@@ -35,9 +35,10 @@
  *
  * A timezone.
  *
- * Timezones are global to the #GWeatherWorld; they can be gotten
- * by passing gweather_timezone_get_by_tzid() with a tzid like
- * "America/New_York" or "Europe/London".
+ * Timezones are global to the GWeather world (as obtained by
+ * gweather_location_get_world()); they can be gotten by passing
+ * gweather_timezone_get_by_tzid() with a tzid like "America/New_York"
+ * or "Europe/London".
  */
 
 struct _GWeatherTimezone {
diff --git a/libgweather/gweather-weather.h b/libgweather/gweather-weather.h
index c473991..5496814 100644
--- a/libgweather/gweather-weather.h
+++ b/libgweather/gweather-weather.h
@@ -127,6 +127,32 @@ gboolean                 gweather_info_is_daytime          (GWeatherInfo *info);
 
 /* values retrieving functions */
 
+/**
+ * GWeatherWindDirection:
+ * @GWEATHER_WIND_INVALID: value not available
+ * @GWEATHER_WIND_VARIABLE: variable throughout the day
+ * @GWEATHER_WIND_N: north
+ * @GWEATHER_WIND_NNE: north-north-east
+ * @GWEATHER_WIND_NE: north-east
+ * @GWEATHER_WIND_ENE: east-north-east
+ * @GWEATHER_WIND_E: east
+ * @GWEATHER_WIND_ESE: east-south-east
+ * @GWEATHER_WIND_SE: south-east
+ * @GWEATHER_WIND_SSE: south-south-east
+ * @GWEATHER_WIND_S: south
+ * @GWEATHER_WIND_SSW: south-south-west
+ * @GWEATHER_WIND_SW: south-west
+ * @GWEATHER_WIND_WSW: west-south-west
+ * @GWEATHER_WIND_W: west
+ * @GWEATHER_WIND_WNW: west-north-west
+ * @GWEATHER_WIND_NW: north-west
+ * @GWEATHER_WIND_NNW: north-north-west
+ * @GWEATHER_WIND_LAST: maximum value for the enumeration
+ *
+ * The direction of the prevailing wind. Composite values
+ * such as north-north-east indicate a direction between the
+ * two component value (north and north-east).
+ */
 typedef enum { /*< underscore_name=gweather_wind_direction >*/
     GWEATHER_WIND_INVALID = -1,
     GWEATHER_WIND_VARIABLE,
@@ -151,6 +177,21 @@ typedef enum { /*< underscore_name=gweather_wind_direction >*/
 
 const gchar * gweather_wind_direction_to_string (GWeatherWindDirection wind);
 
+/**
+ * GWeatherSky:
+ * @GWEATHER_SKY_INVALID: value not available
+ * @GWEATHER_SKY_CLEAR: sky completely clear, no clouds visible
+ * @GWEATHER_SKY_BROKEN: sky mostly clear, few clouds
+ * @GWEATHER_SKY_SCATTERED: sky mostly clear, patches of clouds
+ * @GWEATHER_SKY_FEW: few clouds, sky cloudy but patches of sky visible
+ * @GWEATHER_SKY_OVERCAST: sky completely clouded, sun not visible
+ * @GWEATHER_SKY_LAST: the maximum value for the enumeration
+ *
+ * The sky and cloud visibility. In general it is discouraged to
+ * use this value directly to compute the forecast icon: applications
+ * should instead use gweather_info_get_icon_name() or
+ * gweather_info_get_symbolic_icon_name().
+ */
 typedef enum { /*< underscore_name=gweather_sky >*/
     GWEATHER_SKY_INVALID = -1,
     GWEATHER_SKY_CLEAR,
@@ -163,6 +204,13 @@ typedef enum { /*< underscore_name=gweather_sky >*/
 
 const gchar * gweather_sky_to_string (GWeatherSky sky);
 
+/**
+ * GWeatherConditionPhenomenon:
+ * @GWEATHER_PHENOMENON_INVALID: value not available
+ * @GWEATHER_PHENOMENON_NONE: no significant phenomenon
+ *
+ * The current or forecasted significant phenomenon.
+ */
 typedef enum { /*< underscore_name=gweather_phenomenon >*/
     GWEATHER_PHENOMENON_INVALID = -1,
 
@@ -197,6 +245,40 @@ typedef enum { /*< underscore_name=gweather_phenomenon >*/
     GWEATHER_PHENOMENON_LAST
 } GWeatherConditionPhenomenon;
 
+/**
+ * GWeatherConditionQualifier:
+ * @GWEATHER_QUALIFIER_INVALID: value not available
+ * @GWEATHER_QUALIFIER_NONE: no qualifier for the phenomenon
+ * @GWEATHER_QUALIFIER_VICINITY: phenomenon happening in the proximity
+ *                               of the location, not in the actual location
+ * @GWEATHER_QUALIFIER_LIGHT: phenomenon is light or predicted to be light
+ * @GWEATHER_QUALIFIER_MODERATE: phenomenon is moderate or predicted to be
+ *                               moderate
+ * @GWEATHER_QUALIFIER_HEAVY: phenomenon is heavy or predicted to be heavy
+ * @GWEATHER_QUALIFIER_SHALLOW: shallow fog (only valid with
+ *                              %GWEATHER_PHENOMENON_FOG)
+ * @GWEATHER_QUALIFIER_PATCHES: patches of fog (only valid with
+ *                              %GWEATHER_PHENOMENON_FOG)
+ * @GWEATHER_QUALIFIER_PARTIAL: partial fog (only valid with
+ *                             %GWEATHER_PHENOMENON_FOG)
+ * @GWEATHER_QUALIFIER_THUNDERSTORM: phenomenon will be a thunderstorm
+ *                                   and/or will include lightning
+ * @GWEATHER_QUALIFIER_BLOWING: phenomenon is blowing (valid with
+ *                              %GWEATHER_PHENOMENON_SNOW, %GWEATHER_PHENOMENON_SAND,
+ *                              %GWEATHER_PHENOMENON_SPRAY, %GWEATHER_PHENOMENON_DUST)
+ * @GWEATHER_QUALIFIER_SHOWERS: phenomenon is heavy and involves showers
+ * @GWEATHER_QUALIFIER_DRIFTING: phenomenon is moving across (valid
+ *                               with %GWEATHER_PHENOMENON_SAND and
+ *                               %GWEATHER_PHENOMENON_DUST)
+ * @GWEATHER_QUALIFIER_FREEZING: phenomenon is freezing and involves ice
+ * @GWEATHER_QUALIFIER_LAST: maximum value of the enumeration.
+ *
+ * An additional modifier applied to a #GWeatherConditionPhenomenon to
+ * describe the current or forecasted weather conditions.
+ * The exact meaning of each qualifier is described at
+ * http://www.weather.com/glossary/ and
+ * http://www.crh.noaa.gov/arx/wx.tbl.php
+ */
 typedef enum { /*< underscore_name=gweather_qualifier >*/
     GWEATHER_QUALIFIER_INVALID = -1,
 
@@ -219,7 +301,19 @@ typedef enum { /*< underscore_name=gweather_qualifier >*/
     GWEATHER_QUALIFIER_LAST
 } GWeatherConditionQualifier;
 
+/**
+ * GWeatherMoonPhase:
+ *
+ * The current phase of the moon, represented as degrees,
+ * where 0 is the new moon, 90 is the first quarter, etc.
+ */
 typedef gdouble GWeatherMoonPhase;
+
+/**
+ * GWeatherMoonLatitude:
+ *
+ * The moon declension, in degrees.
+ */
 typedef gdouble GWeatherMoonLatitude;
 
 gboolean gweather_info_get_value_update                (GWeatherInfo *info, time_t *value);
@@ -239,6 +333,23 @@ gboolean gweather_info_get_value_moonphase      (GWeatherInfo *info, GWeatherMoo
 gboolean gweather_info_get_upcoming_moonphases  (GWeatherInfo *info, time_t *phases);
 
 typedef struct _GWeatherConditions GWeatherConditions;
+
+/**
+ * GWeatherConditions:
+ * @significant: %TRUE if the struct contains usable data, %FALSE otherwise
+ * @phenomenon: the main weather phenomenon
+ * @qualifier: a modifier for @phenomenon
+ *
+ * A convenient way to describe the current or forecast
+ * weather phenomenon, if significant, and its associated
+ * modifier. If the value is not significant, the weather conditions
+ * are described by gweather_info_get_sky() instead.
+ *
+ * In general it is discouraged to use this value directly to compute
+ * the forecast icon: applications should instead use
+ * gweather_info_get_icon_name() or
+ * gweather_info_get_symbolic_icon_name().
+ */
 struct _GWeatherConditions {
     gboolean significant;
     GWeatherConditionPhenomenon phenomenon;
diff --git a/libgweather/weather.c b/libgweather/weather.c
index ccbbece..7052ffd 100644
--- a/libgweather/weather.c
+++ b/libgweather/weather.c
@@ -1875,8 +1875,8 @@ gweather_info_get_value_sunset (GWeatherInfo *info, time_t *value)
 /**
  * gweather_info_get_value_moonphase:
  * @info: a #GWeatherInfo
- * @value: (out): the current moon phase (represented as the visible percentage)
- * @lat: (out): the latitude the moon is at (???)
+ * @value: (out): the current moon phase
+ * @lat: (out): the moon declension
  *
  * Returns: TRUE is @value is valid, FALSE otherwise.
  */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]