From 08465d91c3b9b4c3300f703c410e50721b9e8dfa Mon Sep 17 00:00:00 2001 From: "Gergely POLONKAI (W00d5t0ck)" Date: Mon, 16 Sep 2013 13:20:53 +0200 Subject: [PATCH] Continued library documentation. 81% is covered already. --- src/gswe-moment.c | 5 +- src/gswe-moment.h | 7 +++ src/gswe-timestamp.c | 136 +++++++++++++++++++++++++++++++++++++++++++ src/gswe-timestamp.h | 16 +++++ src/gswe-types.h | 37 ++++++++++++ 5 files changed, 198 insertions(+), 3 deletions(-) diff --git a/src/gswe-moment.c b/src/gswe-moment.c index 24b7694..7246219 100644 --- a/src/gswe-moment.c +++ b/src/gswe-moment.c @@ -387,10 +387,9 @@ gswe_moment_get_house_system(GsweMoment *moment) /** * gswe_moment_error_quark: * - * Returns the #GQuark that will be used for #GError values returned by the - * SWE-GLib API. + * Gets the GsweMoment Error Quark. * - * Returns: a GQuark used to identify errors coming from the SWE-GLib API + * Return value: a #GQuark */ G_DEFINE_QUARK(gswe-moment-error-quark, gswe_moment_error); diff --git a/src/gswe-moment.h b/src/gswe-moment.h index 5794696..1ed8cf7 100644 --- a/src/gswe-moment.h +++ b/src/gswe-moment.h @@ -34,6 +34,13 @@ typedef struct _GsweMoment GsweMoment; typedef struct _GsweMomentClass GsweMomentClass; typedef struct _GsweMomentPrivate GsweMomentPrivate; +/** + * GSWE_MOMENT_ERROR: + * + * Error domain for GsweMoment. Errors in this domain will be from + * #GsweMomentError enumeration. See #GError for more information on error + * domains. + */ #define GSWE_MOMENT_ERROR gswe_moment_error_quark() GQuark gswe_moment_error_quark(void); diff --git a/src/gswe-timestamp.c b/src/gswe-timestamp.c index 0f138ad..c3aaf20 100644 --- a/src/gswe-timestamp.c +++ b/src/gswe-timestamp.c @@ -381,6 +381,16 @@ gswe_timestamp_calculate_gregorian(GsweTimestamp *timestamp) g_warning("This method is not implemented yet."); } +/** + * gswe_timestamp_set_instant_recalc: + * @timestamp: a GsweTimestamp + * @instant_recalc: the new value + * @err: a #GError + * + * Sets the value of the instant-recalc property. For details, see the + * property's description. @err is populated with calculation errors if + * @instant_recalc is TRUE and a calculation error happens. + */ void gswe_timestamp_set_instant_recalc(GsweTimestamp *timestamp, gboolean instant_recalc, GError **err) { @@ -397,6 +407,24 @@ gswe_timestamp_get_instant_recalc(GsweTimestamp *timestamp) return timestamp->priv->instant_recalc; } +/** + * gswe_timestamp_set_gregorian_year: + * @timestamp: a GsweTimestamp + * @year: the new Gregorian year + * @month: the new Gregorian month + * @day: the new Gregorian day + * @hour: the new hour value + * @minute: the new minute value + * @second: the new second value + * @microsecond: the new microsecond value + * @time_zone_offset: the time zone offset, in hours + * @err: a #GError + * + * Sets the Gregorian date of @timestamp. @err is populated with calculation + * errors if the instant-recalc property is + * TRUE + */ void gswe_timestamp_set_gregorian_full(GsweTimestamp *timestamp, gint year, gint month, gint day, gint hour, gint minute, gint second, gint microsecond, gdouble time_zone_offset, GError **err) { @@ -417,6 +445,15 @@ gswe_timestamp_set_gregorian_full(GsweTimestamp *timestamp, gint year, gint mont gswe_timestamp_emit_changed(timestamp); } +/** + * gswe_timestamp_set_gregorian_year: + * @timestamp: a GsweTimestamp + * @gregorian_year: the new Gregorian year + * @err: a #GError + * + * Sets the Gregorian year of @timestamp. @err is populated with calculation + * errors if the instant-recalc property is TRUE + */ void gswe_timestamp_set_gregorian_year(GsweTimestamp *timestamp, gint gregorian_year, GError **err) { @@ -430,6 +467,14 @@ gswe_timestamp_set_gregorian_year(GsweTimestamp *timestamp, gint gregorian_year, gswe_timestamp_emit_changed(timestamp); } +/** + * gswe_timestamp_get_gregorian_year: + * @timestamp: a GsweTimestamp + * + * Returns the Gregorian year of @timestamp. + * + * Returns: the year part of @timestamp's Gregorian Date value. + */ gint gswe_timestamp_get_gregorian_year(GsweTimestamp *timestamp) { @@ -438,6 +483,17 @@ gswe_timestamp_get_gregorian_year(GsweTimestamp *timestamp) return timestamp->priv->gregorian_year; } +/** + * gswe_timestamp_set_gregorian_month: + * @timestamp: a GsweTimestamp + * @gregorian_month: the new Gregorian month + * @err: a #GError + * + * Sets the Gregorian month of @timestamp. @err is populated with calculation + * errors if the instant-recalc property is + * TRUE + */ void gswe_timestamp_set_gregorian_month(GsweTimestamp *timestamp, gint gregorian_month, GError **err) { @@ -459,6 +515,17 @@ gswe_timestamp_get_gregorian_month(GsweTimestamp *timestamp) return timestamp->priv->gregorian_month; } +/** + * gswe_timestamp_set_gregorian_day: + * @timestamp: a GsweTimestamp + * @gregorian_day: the new Gregorian day + * @err: a #GError + * + * Sets the Gregorian day of @timestamp. @err is populated with calculation + * errors if the instant-recalc property is + * TRUE + */ void gswe_timestamp_set_gregorian_day(GsweTimestamp *timestamp, gint gregorian_day, GError **err) { @@ -480,6 +547,17 @@ gswe_timestamp_get_gregorian_day(GsweTimestamp *timestamp) return timestamp->priv->gregorian_day; } +/** + * gswe_timestamp_set_gregorian_hour: + * @timestamp: a GsweTimestamp + * @gregorian_hour: the new hour value + * @err: a #GError + * + * Sets the hour value of @timestamp, which may be modified by the time zone. + * @err is populated with calculation errors if the instant-recalc property is + * TRUE + */ void gswe_timestamp_set_gregorian_hour(GsweTimestamp *timestamp, gint gregorian_hour, GError **err) { @@ -501,6 +579,17 @@ gswe_timestamp_get_gregorian_hour(GsweTimestamp *timestamp) return timestamp->priv->gregorian_hour; } +/** + * gswe_timestamp_set_gregorian_minute: + * @timestamp: a GsweTimestamp + * @gregorian_minute: the new minute value + * @err: a #GError + * + * Sets the minute value of @timestamp, which may be modified by the timezone. + * @err is populated with calculation errors if the instant-recalc property is + * TRUE + */ void gswe_timestamp_set_gregorian_minute(GsweTimestamp *timestamp, gint gregorian_minute, GError **err) { @@ -522,6 +611,17 @@ gswe_timestamp_get_gregorian_minute(GsweTimestamp *timestamp) return timestamp->priv->gregorian_minute; } +/** + * gswe_timestamp_set_gregorian_second: + * @timestamp: a GsweTimestamp + * @gregorian_second: the new second value + * @err: a #GError + * + * Sets the second value of @timestamp, which may be modified by the timezone. + * @err is populated with calculation errors if the instant-recalc property is + * TRUE. + */ void gswe_timestamp_set_gregorian_second(GsweTimestamp *timestamp, gint gregorian_second, GError **err) { @@ -543,6 +643,17 @@ gswe_timestamp_get_gregorian_second(GsweTimestamp *timestamp) return timestamp->priv->gregorian_second; } +/** + * gswe_timestamp_set_gregorian_microsecond: + * @timestamp: a GsweTimestamp + * @gregorian_microsecond: the new microsecond value + * @err: a #GError + * + * Sets the microsecond value of @timestamp. @err is populated with calculation + * errors if the instant-recalc property is + * TRUE + */ void gswe_timestamp_set_gregorian_microsecond(GsweTimestamp *timestamp, gint gregorian_microsecond, GError **err) { @@ -564,6 +675,16 @@ gswe_timestamp_get_gregorian_microsecond(GsweTimestamp *timestamp) return timestamp->priv->gregorian_microsecond; } +/** + * gswe_timestamp_set_gregorian_timezone: + * @timestamp: a GsweTimestamp + * @gregorian_timezone_offset: the offset of the desired time zone, in hours + * @err: a #GError + * + * Sets the time zone used in Gregorian date calculations. @err is populated + * with calculation errors if the instant-recalc property's value is TRUE and a + * calculation error happens. + */ void gswe_timestamp_set_gregorian_timezone(GsweTimestamp *timestamp, gdouble gregorian_timezone_offset, GError **err) { @@ -617,6 +738,14 @@ gswe_timestamp_calculate_julian(GsweTimestamp *timestamp, GError **err) } } +/** + * gswe_timestamp_set_julian_day: + * @timestamp: A GsweTimestamp + * @julian_day: The Julian day number, with hours included as fractions + * + * Sets the Julian day value of the timestamp. The Gregorian date will be + * calculated as requested. + */ void gswe_timestamp_set_julian_day(GsweTimestamp *timestamp, gdouble julian_day) { @@ -638,6 +767,13 @@ gswe_timestamp_get_julian_day(GsweTimestamp *timestamp, GError **err) return timestamp->priv->julian_day; } +/** + * gswe_timestamp_error_quark: + * + * Gets the GsweTimestamp Error Quark. + * + * Return value: a #GQuark + */ G_DEFINE_QUARK(gswe-timestamp-error-quark, gswe_timestamp_error); /** diff --git a/src/gswe-timestamp.h b/src/gswe-timestamp.h index 71488c1..f51b12f 100644 --- a/src/gswe-timestamp.h +++ b/src/gswe-timestamp.h @@ -33,6 +33,13 @@ typedef struct _GsweTimestamp GsweTimestamp; typedef struct _GsweTimestampClass GsweTimestampClass; typedef struct _GsweTimestampPrivate GsweTimestampPrivate; +/** + * GSWE_TIMESTAMP_ERROR: + * + * Error domain for GsweTimestamp. Errors in this domain will be from + * #GsweTimestampError enumeration. See #GError for more information on error + * domains. + */ #define GSWE_TIMESTAMP_ERROR (gswe_timestamp_error_quark()) GQuark gswe_timestamp_error_quark(void); @@ -48,6 +55,8 @@ GQuark gswe_timestamp_error_quark(void); * @GSWE_TIMESTAMP_ERROR_SWE_ERROR: denotes an error detected by the Swiss * Ephemeris library, converted from their * static char array to a #GError + * + * Error codes returned by GsweTimestamp functions. */ typedef enum { GSWE_TIMESTAMP_ERROR_SUCCESS, @@ -57,6 +66,11 @@ typedef enum { GSWE_TIMESTAMP_ERROR_SWE_ERROR } GsweTimestampError; +/** + * GsweTimestamp: + * + * The GsweTimestamp object's instance definition. + */ struct _GsweTimestamp { /* Parent instance structure */ GObject parent_instance; @@ -70,6 +84,8 @@ struct _GsweTimestamp { /** * GsweTimestampClass: * @parent_class: the parent class structure (#GObjectClass) + * + * The GsweTimestamp object's class definition. */ struct _GsweTimestampClass { /* Parent class */ diff --git a/src/gswe-types.h b/src/gswe-types.h index 8b93762..3272196 100644 --- a/src/gswe-types.h +++ b/src/gswe-types.h @@ -58,6 +58,8 @@ * @GSWE_PLANET_MC: midheaven (Medium Coeli) * @GSWE_PLANET_VERTEX: the Vertex (the point where the ecliptic meats the * primal vertical) + * + * This enum holds the planet identifiers known by SWE-GLib. */ typedef enum { GSWE_PLANET_NONE, @@ -99,6 +101,8 @@ typedef enum { * @GSWE_SIGN_CAPRICORN: the Capricorn sign (Goat) * @GSWE_SIGN_AQUARIUS: the Aquarius sign (Water Bearer) * @GSWE_SIGN_PISCES: the Pisces sign (Fish) + * + * The zodiac signs known by SWE-GLib by default. */ typedef enum { GSWE_SIGN_NONE, @@ -130,6 +134,8 @@ typedef enum { * @GSWE_ASPECT_SESQUISQUARE: sesqui-square (135°) * @GSWE_ASPECT_BIQUINTILE: bi-quintile (144°) * @GSWE_ASPECT_QUINCUNX: quincunx (150°) + * + * The aspects known by SWE-GLib by default. */ typedef enum { GSWE_ASPECT_NONE, @@ -155,6 +161,8 @@ typedef enum { * @GSWE_ANTISCION_AXIS_CANCER: mirror on the Cancer/Capricorn (90°-270°) axis * @GSWE_ANTISCION_AXIS_MID_LEO: mirror on the middle of Leo/Aquarius * (135°-315°) axis + * + * The antiscion axes known by SWE-GLib by default. */ typedef enum { GSWE_ANTISCION_AXIS_NONE, @@ -171,6 +179,8 @@ typedef enum { * @GSWE_ELEMENT_EARTH: the Earth element * @GSWE_ELEMENT_AIR: the Air element * @GSWE_ELEMENT_WATER: the Water element + * + * The elements as known by the SWE-GLib library. */ typedef enum { GSWE_ELEMENT_NONE, @@ -186,6 +196,8 @@ typedef enum { * @GSWE_QUALITY_CARDINAL: Cardinal quality * @GSWE_QUALITY_FIX: Fix quality * @GSWE_QUALITY_MUTABLE: Mutable quality + * + * The qualities as known by the SWE-GLib library. */ typedef enum { GSWE_QUALITY_NONE, @@ -200,6 +212,8 @@ typedef enum { * @GSWE_HOUSE_SYSTEM_PLACIDUS: Placidus house system * @GSWE_HOUSE_SYSTEM_KOCH: Koch house system * @GSWE_HOUSE_SISTEM_EQUAL: Equal house system + * + * The house systems currently known by SWE-GLib. */ typedef enum { GSWE_HOUSE_SYSTEM_NONE, @@ -219,6 +233,8 @@ typedef enum { * @GSWE_MOON_PHASE_WANING_HALF: Second Half * @GSWE_MOON_PHASE_WANING_CRESCENT: Waning crescent Moon * @GSWE_MOON_PHASE_DARK: Dark Moon + * + * The phases of the Moon. */ typedef enum { GSWE_MOON_PHASE_NEW, @@ -251,6 +267,9 @@ typedef enum { * @exile_sign_2: the second sign in which the planet is in exile * @exalted_sign: the sign in which the planet is exalted * @fall_sign: the sign in which the planet is in fall + * + * This struct holds different informations of planets. You should never modify + * such a structure unless you really know what you are doing. */ typedef struct { GswePlanet planet; @@ -273,6 +292,8 @@ typedef struct { * @name: the name of this sign * @element: the element of the sign * @quality: the quality of the sign + * + * Holds information about zodiac signs known by SWE-GLib. */ typedef struct { GsweZodiac sign_id; @@ -286,6 +307,8 @@ typedef struct { * @system: the house system's ID * @sweph_id: the character value that represents this house system in the Swiss Ephemeris library * @name: the name of this house system + * + * Holds information about house systems known by SWE-GLib. */ typedef struct { GsweHouseSystem system; @@ -301,6 +324,8 @@ typedef struct { * @orb_modifier: the modifier of the orb (the maximum allowable difference from an exact orb) * @harmonic: shows whether this aspect is harmonic or not * @major: shows whether this aspect is major (Ptolemaic) or not + * + * Holds informations about the aspects known by SWE-GLib. */ typedef struct { GsweAspect aspect; @@ -317,6 +342,8 @@ typedef struct { * @start_sign: represents the sign in whict the mirror axis starts * @name: the name of the mirror * @middle_axis: if TRUE, the axis runs through the middle of its starting sign + * + * Holds information of antiscion axes. */ typedef struct { GsweAntiscionAxis axis_id; @@ -329,6 +356,8 @@ typedef struct { * GsweMoonPhaseData: * @phase: the current phase of the Moon * @illumination: the portion of the Moon that is currently illuminated + * + * Holds information of a Moon phase. */ typedef struct { GsweMoonPhase phase; @@ -347,6 +376,8 @@ GType gswe_moon_phase_data_get_type(void); * @house: Number of the house in which the planet is in * @sign: A GsweSignInfo structure, holding every information about the sign the planet is in * @revision: An internal version number of the calculation + * + * Holds information of a given planet. */ typedef struct { GswePlanet planet_id; @@ -385,6 +416,8 @@ GType gswe_coordinates_get_type(void); * @cusp_position: the position of the house's cusp on the sky * @sign: the #GsweSignInfo structure associated with the sign in which the * house cusp is in + * + * Holds information of a given house. */ typedef struct { guint house; @@ -404,6 +437,8 @@ GType gswe_house_data_get_type(void); * @aspect_info: the #GsweAspectInfo structure associated with the aspect * @difference: the difference in percent between an exact aspect and this * given aspect + * + * Holds information about a given aspect. */ typedef struct { GswePlanetData *planet1; @@ -426,6 +461,8 @@ GType gswe_aspect_data_get_type(void); * antiscion * @difference: the difference in degrees between an exact antiscion and this * given antiscion + * + * Holds information about a given antiscion. */ typedef struct { GswePlanetData *planet1;