From 3195fa266b86c088347885beefe3c9f1cb97d693 Mon Sep 17 00:00:00 2001 From: "Gergely POLONKAI (W00d5t0ck)" Date: Thu, 5 Sep 2013 19:50:57 +0200 Subject: [PATCH] Added some documentation to stop GObject introspection and GTK-Doc complaining Still many missing... --- src/gswe-moment.c | 76 +++++++++++++++++++++++++++++++++++++++++--- src/gswe-moment.h | 37 +++++++++++++++++++++ src/gswe-timestamp.h | 12 +++++++ src/gswe-types.h | 43 +++++++++++++++++++++++++ 4 files changed, 163 insertions(+), 5 deletions(-) diff --git a/src/gswe-moment.c b/src/gswe-moment.c index 2910ab8..3305ee7 100644 --- a/src/gswe-moment.c +++ b/src/gswe-moment.c @@ -344,6 +344,14 @@ gswe_moment_calculate_house_positions(GsweMoment *moment) } } +/** + * gswe_moment_get_house_cusps: + * @moment: The GsweMoment object to operate on + * + * Calculate house cusp positions based on the house system, location and time set in @moment. + * + * Returns: (element-type GsweHouseData) (transfer none): a GList of #GsweHouseData + */ GList * gswe_moment_get_house_cusps(GsweMoment *moment) { @@ -452,6 +460,14 @@ gswe_moment_calculate_all_planets(GsweMoment *moment) g_list_foreach(moment->priv->planet_list, calculate_planet, moment); } +/** + * gswe_moment_get_planets: + * @moment: The GsweMoment to operate on + * + * Get all the planets added to @moment. + * + * Returns: (element-type GswePlanetData) (transfer none): A #GList of #GswePlanetData. + */ GList * gswe_moment_get_planets(GsweMoment *moment) { @@ -700,8 +716,9 @@ gswe_moment_calculate_aspects(GsweMoment *moment) * Gets all planetary aspects between the planets added by * gswe_moment_add_planet() or gswe_moment_add_all_planets(). * - * Returns: a GList of #GsweAspectData. Both the GList and GsweAspectData - * objects belong to @moment, and should not be freed or modified. + * Returns: (element-type GsweAspectData) (transfer none): a GList of + * #GsweAspectData. Both the GList and GsweAspectData objects belong + * to @moment, and should not be freed or modified. */ GList * gswe_moment_get_aspects(GsweMoment *moment) @@ -719,9 +736,10 @@ gswe_moment_get_aspects(GsweMoment *moment) * Get all the aspects between @planet and all the other planets added with * gswe_moment_add_planet() or gswe_moment_add_all_planets(). * - * Returns: a GList of #GsweAspectData. The GsweAspectData structures belong to - * @moment, but the GList should be freed using g_list_free(). If the - * planet has no aspects, or the planet has not been added to @moment, + * Returns: (element-type GsweAspectData) (transfer container): a #GList of + * #GsweAspectData. The GsweAspectData structures belong to @moment, + * but the GList should be freed using g_list_free(). If the planet + * has no aspects, or the planet has not been added to @moment, * returns NULL. */ GList * @@ -839,6 +857,15 @@ gswe_moment_calculate_mirrorpoints(GsweMoment *moment) moment->priv->mirrorpoint_revision = moment->priv->revision; } +/** + * gswe_moment_get_all_mirrorpoints: + * @moment: The GsweMoment object to operate on. + * + * Get all found mirrorpoints between planets in @moment. + * + * Returns: (element-type GsweMirrorData) (transfer none): A #GList of + * #GsweMirrorData. + */ GList * gswe_moment_get_all_mirrorpoints(GsweMoment *moment) { @@ -847,6 +874,19 @@ gswe_moment_get_all_mirrorpoints(GsweMoment *moment) return moment->priv->mirrorpoint_list; } +/** + * gswe_moment_get_all_planet_mirrorpoints: + * @moment: The GsweMoment object to operate on. + * @planet: The planet whose mirrorpoint planets are requested. + * + * Get all the mirrorpoint planets on all registered mirrors for @planet. + * + * Returns: (element-type GsweMirrorData) (transfer container): a #GList of + * #GsweMirrorData. The GsweMirrorData structures belong to @moment, + * but the GList should be freed using g_list_free(). If no planet + * has any mirrorpoints, or the planet has not been added to @moment, + * returns NULL. + */ GList * gswe_moment_get_all_planet_mirrorpoints(GsweMoment *moment, GswePlanet planet) { @@ -866,6 +906,18 @@ gswe_moment_get_all_planet_mirrorpoints(GsweMoment *moment, GswePlanet planet) return ret; } +/** + * gswe_moment_get_mirror_mirrorpoints: + * @moment: The GsweMoment object to operate on. + * @mirror: The mirror on which you want to search for mirrored planets. + * + * Get all the mirrorpoint planets on the specified mirror @mirror. + * + * Returns: (element-type GsweMirrorData) (transfer container): a #GList of + * #GsweMirrorData. The GsweMirrorData structures belong to @moment, + * but the GList should be freed using g_list_free(). If there are + * no mirrored planets on the given mirror, returns NULL. + */ GList * gswe_moment_get_mirror_mirrorpoints(GsweMoment *moment, GsweMirror mirror) { @@ -885,6 +937,20 @@ gswe_moment_get_mirror_mirrorpoints(GsweMoment *moment, GsweMirror mirror) return ret; } +/** + * gswe_moment_get_mirror_planet_mirrorpoints: + * @moment: the GsweMoment object to operate on + * @mirror: the mirror on which you want to search for mirrored planets + * @planet: the planet whose mirrorpoint planets are requested + * + * Get the mirrorpoint planets of @planet as seen in @mirror. + * + * Returns: (element-type GsweMirrorData) (transfer container): a #GList of + * #GsweMirrorData. The GsweMirrorData structires belong to @moment, + * but the GList should be freed using g_list_free(). If the planet + * has no mirrorpoints, or the planet has not been added to @moment, + * returns NULL. + */ GList * gswe_moment_get_mirror_planet_mirrorpoints(GsweMoment *moment, GsweMirror mirror, GswePlanet planet) { diff --git a/src/gswe-moment.h b/src/gswe-moment.h index 8d8a436..7b8f7b6 100644 --- a/src/gswe-moment.h +++ b/src/gswe-moment.h @@ -46,6 +46,7 @@ typedef struct _GsweCoordinates { * @planet_id: A GswePlanet, the identifier of the planet * @planet_info: A GswePlanetInfo structure, holding every information about the planet * @position: The longitude position of the planet + * @retrograde: TRUE if the planet is in retrograde motion * @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 @@ -60,17 +61,40 @@ typedef struct { guint revision; } GswePlanetData; +/** + * GsweHouseData: + * @house: the number of the house (usually in the range [1;12]. Sometimes may + * be [1;36]. + * @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 + */ typedef struct { guint house; gdouble cusp_position; GsweSignInfo *sign; } GsweHouseData; +/** + * GsweMoonPhaseData: + * @phase: the current phase of the Moon + * @illumination: the portion of the Moon that is currently illuminated + */ typedef struct { GsweMoonPhase phase; gdouble illumination; } GsweMoonPhaseData; +/** + * GsweAspectData: + * @planet1: the first planet in the aspect + * @planet2: the second planet in the aspect + * @distance: the distance between the two planets, in degrees + * @aspect: the aspect between the two planets + * @aspect_info: the #GsweAspectInfo structure associated with the aspect + * @difference: the difference in percent between an exact aspect and this + * given aspect + */ typedef struct { GswePlanetData *planet1; GswePlanetData *planet2; @@ -80,6 +104,15 @@ typedef struct { gdouble difference; } GsweAspectData; +/** + * GsweMirrorData: + * @planet1: the first planet in the mirror + * @planet2: the second planet in the mirror + * @mirror: the mirror on which this mirrorpoint is + * @mirror_info: the #GsweMirrorInfo structure associated with this mirror + * @difference: the difference in degrees between an exact mirror and this + * given mirrorpoint + */ typedef struct { GswePlanetData *planet1; GswePlanetData *planet2; @@ -98,6 +131,10 @@ struct _GsweMoment { GsweMomentPrivate *priv; }; +/** + * GsweMomentClass: + * @parent_class: the parent class (#GObjectClass) + */ struct _GsweMomentClass { /* Parent class structure */ GObjectClass parent_class; diff --git a/src/gswe-timestamp.h b/src/gswe-timestamp.h index f887aee..2161f92 100644 --- a/src/gswe-timestamp.h +++ b/src/gswe-timestamp.h @@ -17,6 +17,13 @@ typedef struct _GsweTimestampPrivate GsweTimestampPrivate; #define GSWE_TIMESTAMP_ERROR (gswe_timestamp_error_quark()) GQuark gswe_timestamp_error_quark(void); +/** + * GsweTimestampError: + * @GSWE_TIMESTAMP_ERROR_INVALID_DATE: the Gregorian date specified in this + * #GsweTimestamp is invalid + * @GSWE_TIMESTAMP_ERROR_INVALID_TIME: the time specified in this + * #GsweTimestamp is invalid + */ typedef enum { GSWE_TIMESTAMP_ERROR_INVALID_DATE, GSWE_TIMESTAMP_ERROR_INVALID_TIME @@ -32,11 +39,16 @@ struct _GsweTimestamp { GsweTimestampPrivate *priv; }; +/** + * GsweTimestampClass: + * @parent_class: the parent class structure (#GObjectClass) + */ struct _GsweTimestampClass { /* Parent class */ GObjectClass parent_class; /* Class members */ + /*< private >*/ void (*changed)(GsweTimestamp *self); }; diff --git a/src/gswe-types.h b/src/gswe-types.h index 8cee229..1e27a01 100644 --- a/src/gswe-types.h +++ b/src/gswe-types.h @@ -3,6 +3,33 @@ #include +/** + * GswePlanet: + * @GSWE_PLANET_NONE: no planet + * @GSWE_PLANET_SUN: the Sun + * @GSWE_PLANET_MOON: the Moon + * @GSWE_PLANET_MERCURY: planet Mercury + * @GSWE_PLANET_VENUS: planet Venus + * @GSWE_PLANET_EARTH: planet Earth + * @GSWE_PLANET_MARS: planet Mars + * @GSWE_PLANET_JUPITER: planet Jupiter + * @GSWE_PLANET_SATURN: planet Saturn + * @GSWE_PLANET_URANUS: planet Uranus + * @GSWE_PLANET_NEPTUNE: planet Neptune + * @GSWE_PLANET_PLUTO: planet Pluto + * @GSWE_PLANET_CHIRON: dwarf planet Chiron + * @GSWE_PLANET_CERES: dwarf planet Ceres + * @GSWE_PLANET_PALLAS: dwarf planet Pallas + * @GSWE_PLANET_JUNO: dwarf planet Juno + * @GSWE_PLANET_VESTA: dwarf planet Vesta + * @GSWE_PLANET_MOON_NODE: the mean ascending (north) Moon node + * @GSWE_PLANET_MOON_APOGEE: the mean Moon apogee (sometimes called Dark Moon, + * or Lilith) + * @GSWE_PLANET_ASCENDENT: the ascendent + * @GSWE_PLANET_MC: midheaven (Medium Coeli) + * @GSWE_PLANET_VERTEX: the Vertex (the point where the ecliptic meats the + * primal vertical) + */ typedef enum { GSWE_PLANET_NONE, GSWE_PLANET_SUN, @@ -28,6 +55,22 @@ typedef enum { GSWE_PLANET_VERTEX } GswePlanet; +/** + * GsweZodiac: + * @GSWE_SIGN_NONE: no sign + * @GSWE_SIGN_ARIES: the Aries sign (Ram) + * @GSWE_SIGN_TAURUS: the Taurus sign (Bull) + * @GSWE_SIGN_GEMINI: the Gemini sign (Twins) + * @GSWE_SIGN_CANCER: the Cancer sign (Crab) + * @GSWE_SIGN_LEO: the Leo sign (Lion) + * @GSWE_SIGN_VIRGO: the Virgo sign (Maid) + * @GSWE_SIGN_LIBRA: the Libra sign (Scales) + * @GSWE_SIGN_SCORPIO: the Scorpio sign (Scorpion) + * @GSWE_SIGN_SAGITTARIUS: the Sagittarius sign (Archer) + * @GSWE_SIGN_CAPRICORN: the Capricorn sign (Goat) + * @GSWE_SIGN_AQUARIUS: the Aquarius sign (Water Bearer) + * @GSWE_SIGN_PISCES: the Pisces sign (Fish) + */ typedef enum { GSWE_SIGN_NONE, GSWE_SIGN_ARIES,