From 3f60d2fac1d48ed00ddbf4e7c2898cdc71a742c0 Mon Sep 17 00:00:00 2001 From: Don Cross Date: Wed, 5 Jun 2019 19:23:25 -0400 Subject: [PATCH] Added documentation for Astronomy_LongitudeFromSun and Astronomy_MoonPhase. --- generate/template/astronomy.c | 60 +++++++++++++++++++++++++++++++++++ source/c/README.md | 51 +++++++++++++++++++++++++++++ source/c/astronomy.c | 60 +++++++++++++++++++++++++++++++++++ 3 files changed, 171 insertions(+) diff --git a/generate/template/astronomy.c b/generate/template/astronomy.c index e9eb8072..0c41420b 100644 --- a/generate/template/astronomy.c +++ b/generate/template/astronomy.c @@ -2849,6 +2849,42 @@ astro_elongation_t Astronomy_SearchMaxElongation(astro_body_t body, astro_time_t return ElongError(ASTRO_SEARCH_FAILURE); } +/** + * @brief + * Returns a body's ecliptic longitude with respect to the Sun, as seen from the Earth. + * + * This function can be used to determine where a planet appears around the ecliptic plane + * (the plane of the Earth's orbit around the Sun) as seen from the Earth, + * relative to the Sun's apparent position. + * + * The angle starts at 0 when the body and the Sun are at the same ecliptic longitude + * as seen from the Earth. The angle increases in the prograde direction + * (the direction that the planets orbit the Sun and the Moon orbits the Earth). + * + * When the angle is 180 degrees, it means the Sun and the body appear on opposite sides + * of the sky for an Earthly observer. When `body` is a planet whose orbit around the + * Sun is farther than the Earth's, 180 degrees indicates opposition. For the moon, it indicates + * a full moon. + * + * The angle keeps increasing up to 360 degrees as the body's apparent prograde + * motion continues relative to the Sun. When the angle reaches 360 degrees, it starts + * over at 0 degrees. + * + * Values between 0 and 180 degrees indicate that the body is visible in the evening sky + * after sunset. Values between 180 degrees and 360 degrees indicate that the body + * is visible in the morning sky before sunrise. + * + * @param body + * The celestial body for which to find longitude from the Sun. + * + * @param time + * The date and time of the observation. + * + * @return + * On success, the `status` field in the returned structure holds `ASTRO_SUCCESS` and + * the `angle` field holds a value in the range [0, 360). + * On failure, the `status` field contains some other value indicating an error condition. + */ astro_angle_result_t Astronomy_LongitudeFromSun(astro_body_t body, astro_time_t time) { astro_vector_t sv, bv; @@ -2873,6 +2909,30 @@ astro_angle_result_t Astronomy_LongitudeFromSun(astro_body_t body, astro_time_t return result; } +/** + * @brief + * Returns the Moon's phase as an angle from 0 to 360 degrees. + * + * This function determines the phase of the Moon using its apparent + * ecliptic longitude relative to the Sun, as seen from the center of the Earth. + * Certain values of the angle have conventional definitions: + * + * - 0 = new moon + * - 90 = first quarter + * - 180 = full moon + * - 270 = third quarter + * + * @param time + * The date and time of the observation. + * + * @return + * On success, the function returns the angle as described above in the `angle` + * field and `ASTRO_SUCCESS` in the `status` field. + * The function should always succeed, but it is a good idea for callers to check + * the `status` field in the returned structure. + * Any other value in `status` indicates a failure that should be + * [reported as an issue](https://github.com/cosinekitty/astronomy/issues). + */ astro_angle_result_t Astronomy_MoonPhase(astro_time_t time) { return Astronomy_LongitudeFromSun(BODY_MOON, time); diff --git a/source/c/README.md b/source/c/README.md index aecfa08e..615db156 100644 --- a/source/c/README.md +++ b/source/c/README.md @@ -437,6 +437,32 @@ This function optionally corrects for atmospheric refraction. For most uses, it ### Astronomy_LongitudeFromSun(body, time) ⇒ [`astro_angle_result_t`](#astro_angle_result_t) +**Returns a body's ecliptic longitude with respect to the Sun, as seen from the Earth.** + + + +This function can be used to determine where a planet appears around the ecliptic plane (the plane of the Earth's orbit around the Sun) as seen from the Earth, relative to the Sun's apparent position. + +The angle starts at 0 when the body and the Sun are at the same ecliptic longitude as seen from the Earth. The angle increases in the prograde direction (the direction that the planets orbit the Sun and the Moon orbits the Earth). + +When the angle is 180 degrees, it means the Sun and the body appear on opposite sides of the sky for an Earthly observer. When `body` is a planet whose orbit around the Sun is farther than the Earth's, 180 degrees indicates opposition. For the moon, it indicates a full moon. + +The angle keeps increasing up to 360 degrees as the body's apparent prograde motion continues relative to the Sun. When the angle reaches 360 degrees, it starts over at 0 degrees. + +Values between 0 and 180 degrees indicate that the body is visible in the evening sky after sunset. Values between 180 degrees and 360 degrees indicate that the body is visible in the morning sky before sunrise. + + + +**Returns:** On success, the `status` field in the returned structure holds `ASTRO_SUCCESS` and the `angle` field holds a value in the range [0, 360). On failure, the `status` field contains some other value indicating an error condition. + + + +| Type | Parameter | Description | +| --- | --- | --- | +| [`astro_body_t`](#astro_body_t) | `body` | The celestial body for which to find longitude from the Sun. | +| [`astro_time_t`](#astro_time_t) | `time` | The date and time of the observation. | + + --- @@ -501,6 +527,31 @@ It is the caller's responsibility to ensure that the parameter values are correc ### Astronomy_MoonPhase(time) ⇒ [`astro_angle_result_t`](#astro_angle_result_t) +**Returns the Moon's phase as an angle from 0 to 360 degrees.** + + + +This function determines the phase of the Moon using its apparent ecliptic longitude relative to the Sun, as seen from the center of the Earth. Certain values of the angle have conventional definitions: + + + +- 0 = new moon +- 90 = first quarter +- 180 = full moon +- 270 = third quarter + + + + +**Returns:** On success, the function returns the angle as described above in the `angle` field and `ASTRO_SUCCESS` in the `status` field. The function should always succeed, but it is a good idea for callers to check the `status` field in the returned structure. Any other value in `status` indicates a failure that should be [reported as an issue](https://github.com/cosinekitty/astronomy/issues). + + + +| Type | Parameter | Description | +| --- | --- | --- | +| [`astro_time_t`](#astro_time_t) | `time` | The date and time of the observation. | + + --- diff --git a/source/c/astronomy.c b/source/c/astronomy.c index 2800bfc0..4d35554d 100644 --- a/source/c/astronomy.c +++ b/source/c/astronomy.c @@ -3905,6 +3905,42 @@ astro_elongation_t Astronomy_SearchMaxElongation(astro_body_t body, astro_time_t return ElongError(ASTRO_SEARCH_FAILURE); } +/** + * @brief + * Returns a body's ecliptic longitude with respect to the Sun, as seen from the Earth. + * + * This function can be used to determine where a planet appears around the ecliptic plane + * (the plane of the Earth's orbit around the Sun) as seen from the Earth, + * relative to the Sun's apparent position. + * + * The angle starts at 0 when the body and the Sun are at the same ecliptic longitude + * as seen from the Earth. The angle increases in the prograde direction + * (the direction that the planets orbit the Sun and the Moon orbits the Earth). + * + * When the angle is 180 degrees, it means the Sun and the body appear on opposite sides + * of the sky for an Earthly observer. When `body` is a planet whose orbit around the + * Sun is farther than the Earth's, 180 degrees indicates opposition. For the moon, it indicates + * a full moon. + * + * The angle keeps increasing up to 360 degrees as the body's apparent prograde + * motion continues relative to the Sun. When the angle reaches 360 degrees, it starts + * over at 0 degrees. + * + * Values between 0 and 180 degrees indicate that the body is visible in the evening sky + * after sunset. Values between 180 degrees and 360 degrees indicate that the body + * is visible in the morning sky before sunrise. + * + * @param body + * The celestial body for which to find longitude from the Sun. + * + * @param time + * The date and time of the observation. + * + * @return + * On success, the `status` field in the returned structure holds `ASTRO_SUCCESS` and + * the `angle` field holds a value in the range [0, 360). + * On failure, the `status` field contains some other value indicating an error condition. + */ astro_angle_result_t Astronomy_LongitudeFromSun(astro_body_t body, astro_time_t time) { astro_vector_t sv, bv; @@ -3929,6 +3965,30 @@ astro_angle_result_t Astronomy_LongitudeFromSun(astro_body_t body, astro_time_t return result; } +/** + * @brief + * Returns the Moon's phase as an angle from 0 to 360 degrees. + * + * This function determines the phase of the Moon using its apparent + * ecliptic longitude relative to the Sun, as seen from the center of the Earth. + * Certain values of the angle have conventional definitions: + * + * - 0 = new moon + * - 90 = first quarter + * - 180 = full moon + * - 270 = third quarter + * + * @param time + * The date and time of the observation. + * + * @return + * On success, the function returns the angle as described above in the `angle` + * field and `ASTRO_SUCCESS` in the `status` field. + * The function should always succeed, but it is a good idea for callers to check + * the `status` field in the returned structure. + * Any other value in `status` indicates a failure that should be + * [reported as an issue](https://github.com/cosinekitty/astronomy/issues). + */ astro_angle_result_t Astronomy_MoonPhase(astro_time_t time) { return Astronomy_LongitudeFromSun(BODY_MOON, time);