From eabbd4b628a43a483b1ecd5dde41cd468f7fa778 Mon Sep 17 00:00:00 2001 From: Don Cross Date: Thu, 24 Oct 2019 22:36:18 -0400 Subject: [PATCH] Added stub documentation of all C# public symbols. This is just to get build errors to go away. Will have to come back and flesh out all of the documentation once I start working on the C# documentation generator. --- .gitignore | 1 + generate/template/astronomy.cs | 147 +++++++++++++++++++++++++++++++++ source/csharp/astronomy.cs | 147 +++++++++++++++++++++++++++++++++ 3 files changed, 295 insertions(+) diff --git a/.gitignore b/.gitignore index 9f94e5dd..aac7c5af 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .vscode +.vs __pycache__ diff --git a/generate/template/astronomy.cs b/generate/template/astronomy.cs index 6fa9ef47..5da4ce55 100644 --- a/generate/template/astronomy.cs +++ b/generate/template/astronomy.cs @@ -29,31 +29,118 @@ using System; namespace CosineKitty { + /// + /// The enumeration of celestial bodies supported by Astronomy Engine. + /// public enum Body { + /// + /// A placeholder value representing an invalid or unknown celestial body. + /// Invalid = -1, + + /// + /// The planet Mercury. + /// Mercury, + + /// + /// The planet Venus. + /// Venus, + + /// + /// The planet Earth. Not allowed for many functions for Earth-based observers. + /// Earth, + + /// + /// The planet Mars. + /// Mars, + + /// + /// The planet Jupiter. + /// Jupiter, + + /// + /// The planet Saturn. + /// Saturn, + + /// + /// The planet Uranus. + /// Uranus, + + /// + /// The planet Neptune. + /// Neptune, + + /// + /// The planet Pluto. + /// Pluto, + + /// + /// The Sun. + /// Sun, + + /// + /// The Earth's natural satellite, the Moon. + /// Moon, } + /// + /// A date and time used for astronomical calculations. + /// public class AstroTime { private static readonly DateTime Origin = new DateTime(2000, 1, 1, 12, 0, 0, DateTimeKind.Utc); + /// + /// UT1/UTC number of days since noon on January 1, 2000. + /// The floating point number of days of Universal Time since noon UTC January 1, 2000. + /// Astronomy Engine approximates UTC and UT1 as being the same thing, although they are + /// not exactly equivalent; UTC and UT1 can disagree by up to plus or minus 0.9 seconds. + /// This approximation is sufficient for the accuracy requirements of Astronomy Engine. + /// + /// Universal Time Coordinate (UTC) is the international standard for legal and civil + /// timekeeping and replaces the older Greenwich Mean Time (GMT) standard. + /// UTC is kept in sync with unpredictable observed changes in the Earth's rotation + /// by occasionally adding leap seconds as needed. + /// + /// UT1 is an idealized time scale based on observed rotation of the Earth, which + /// gradually slows down in an unpredictable way over time, due to tidal drag by the Moon and Sun, + /// large scale weather events like hurricanes, and internal seismic and convection effects. + /// Conceptually, UT1 drifts from atomic time continuously and erratically, whereas UTC + /// is adjusted by a scheduled whole number of leap seconds as needed. + /// + /// The value in `ut` is appropriate for any calculation involving the Earth's rotation, + /// such as calculating rise/set times, culumination, and anything involving apparent + /// sidereal time. + /// + /// Before the era of atomic timekeeping, days based on the Earth's rotation + /// were often known as *mean solar days*. + /// public readonly double ut; + + /// + /// Terrestrial Time days since noon on January 1, 2000. + /// public readonly double tt; + internal double psi; internal double eps; + /// + /// Creates an `AstroTime` object from a Universal Time day value. + /// + /// The number of days after the J2000 epoch. public AstroTime(double ut) { this.ut = ut; @@ -61,29 +148,66 @@ namespace CosineKitty this.psi = this.eps = double.NaN; } + /// + /// Creates an `AstroTime` object from a .NET `DateTime` object. + /// + /// The date and time to be converted to AstroTime format. public AstroTime(DateTime d) : this((d - Origin).TotalDays) { } + /// + /// Converts this object to .NET `DateTime` format. + /// + /// a UTC `DateTime` object for this `AstroTime` value. public DateTime ToUtcDateTime() { return Origin.AddDays(ut).ToUniversalTime(); } + /// + /// Converts this `AstroTime` to ISO 8601 format, expressed in UTC with millisecond resolution. + /// + /// Example: "2019-08-30T17:45:22.763". public override string ToString() { return ToUtcDateTime().ToString("yyyy-MM-ddThh:mm:ss.fffZ"); } } + /// + /// A 3D Cartesian vector whose components are expressed in Astronomical Units (AU). + /// public class AstroVector { + /// + /// The Cartesian x-coordinate of the vector in AU. + /// public readonly double x; + + /// + /// The Cartesian y-coordinate of the vector in AU. + /// public readonly double y; + + /// + /// The Cartesian z-coordinate of the vector in AU. + /// public readonly double z; + + /// + /// The date and time at which this vector is valid. + /// public readonly AstroTime t; + /// + /// Creates an AstroVector. + /// + /// A Cartesian x-coordinate expressed in AU. + /// A Cartesian y-coordinate expressed in AU. + /// A Cartesian z-coordinate expressed in AU. + /// The date and time at which this vector is valid. public AstroVector(double x, double y, double z, AstroTime t) { this.x = x; @@ -93,12 +217,32 @@ namespace CosineKitty } } + /// + /// The location of an observer on (or near) the surface of the Earth. + /// public class Observer { + /// + /// Geographic latitude in degrees north (positive) or south (negative) of the equator. + /// public readonly double Latitude; + + /// + /// Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England. + /// public readonly double Longitude; + + /// + /// The height above (positive) or below (negative) sea level, expressed in meters. + /// public readonly double Height; + /// + /// Creates an Observer object. + /// + /// Geographic latitude in degrees north (positive) or south (negative) of the equator. + /// Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England. + /// The height above (positive) or below (negative) sea level, expressed in meters. public Observer(double latitude, double longitude, double height) { Latitude = latitude; @@ -107,6 +251,9 @@ namespace CosineKitty } } + /// + /// The wrapper class that holds Astronomy Engine functions. + /// public static class Astronomy { private static readonly deltat_entry_t[] DT = $ASTRO_DELTA_T(); diff --git a/source/csharp/astronomy.cs b/source/csharp/astronomy.cs index 8f9c27fe..7acf4216 100644 --- a/source/csharp/astronomy.cs +++ b/source/csharp/astronomy.cs @@ -29,31 +29,118 @@ using System; namespace CosineKitty { + /// + /// The enumeration of celestial bodies supported by Astronomy Engine. + /// public enum Body { + /// + /// A placeholder value representing an invalid or unknown celestial body. + /// Invalid = -1, + + /// + /// The planet Mercury. + /// Mercury, + + /// + /// The planet Venus. + /// Venus, + + /// + /// The planet Earth. Not allowed for many functions for Earth-based observers. + /// Earth, + + /// + /// The planet Mars. + /// Mars, + + /// + /// The planet Jupiter. + /// Jupiter, + + /// + /// The planet Saturn. + /// Saturn, + + /// + /// The planet Uranus. + /// Uranus, + + /// + /// The planet Neptune. + /// Neptune, + + /// + /// The planet Pluto. + /// Pluto, + + /// + /// The Sun. + /// Sun, + + /// + /// The Earth's natural satellite, the Moon. + /// Moon, } + /// + /// A date and time used for astronomical calculations. + /// public class AstroTime { private static readonly DateTime Origin = new DateTime(2000, 1, 1, 12, 0, 0, DateTimeKind.Utc); + /// + /// UT1/UTC number of days since noon on January 1, 2000. + /// The floating point number of days of Universal Time since noon UTC January 1, 2000. + /// Astronomy Engine approximates UTC and UT1 as being the same thing, although they are + /// not exactly equivalent; UTC and UT1 can disagree by up to plus or minus 0.9 seconds. + /// This approximation is sufficient for the accuracy requirements of Astronomy Engine. + /// + /// Universal Time Coordinate (UTC) is the international standard for legal and civil + /// timekeeping and replaces the older Greenwich Mean Time (GMT) standard. + /// UTC is kept in sync with unpredictable observed changes in the Earth's rotation + /// by occasionally adding leap seconds as needed. + /// + /// UT1 is an idealized time scale based on observed rotation of the Earth, which + /// gradually slows down in an unpredictable way over time, due to tidal drag by the Moon and Sun, + /// large scale weather events like hurricanes, and internal seismic and convection effects. + /// Conceptually, UT1 drifts from atomic time continuously and erratically, whereas UTC + /// is adjusted by a scheduled whole number of leap seconds as needed. + /// + /// The value in `ut` is appropriate for any calculation involving the Earth's rotation, + /// such as calculating rise/set times, culumination, and anything involving apparent + /// sidereal time. + /// + /// Before the era of atomic timekeeping, days based on the Earth's rotation + /// were often known as *mean solar days*. + /// public readonly double ut; + + /// + /// Terrestrial Time days since noon on January 1, 2000. + /// public readonly double tt; + internal double psi; internal double eps; + /// + /// Creates an `AstroTime` object from a Universal Time day value. + /// + /// The number of days after the J2000 epoch. public AstroTime(double ut) { this.ut = ut; @@ -61,29 +148,66 @@ namespace CosineKitty this.psi = this.eps = double.NaN; } + /// + /// Creates an `AstroTime` object from a .NET `DateTime` object. + /// + /// The date and time to be converted to AstroTime format. public AstroTime(DateTime d) : this((d - Origin).TotalDays) { } + /// + /// Converts this object to .NET `DateTime` format. + /// + /// a UTC `DateTime` object for this `AstroTime` value. public DateTime ToUtcDateTime() { return Origin.AddDays(ut).ToUniversalTime(); } + /// + /// Converts this `AstroTime` to ISO 8601 format, expressed in UTC with millisecond resolution. + /// + /// Example: "2019-08-30T17:45:22.763". public override string ToString() { return ToUtcDateTime().ToString("yyyy-MM-ddThh:mm:ss.fffZ"); } } + /// + /// A 3D Cartesian vector whose components are expressed in Astronomical Units (AU). + /// public class AstroVector { + /// + /// The Cartesian x-coordinate of the vector in AU. + /// public readonly double x; + + /// + /// The Cartesian y-coordinate of the vector in AU. + /// public readonly double y; + + /// + /// The Cartesian z-coordinate of the vector in AU. + /// public readonly double z; + + /// + /// The date and time at which this vector is valid. + /// public readonly AstroTime t; + /// + /// Creates an AstroVector. + /// + /// A Cartesian x-coordinate expressed in AU. + /// A Cartesian y-coordinate expressed in AU. + /// A Cartesian z-coordinate expressed in AU. + /// The date and time at which this vector is valid. public AstroVector(double x, double y, double z, AstroTime t) { this.x = x; @@ -93,12 +217,32 @@ namespace CosineKitty } } + /// + /// The location of an observer on (or near) the surface of the Earth. + /// public class Observer { + /// + /// Geographic latitude in degrees north (positive) or south (negative) of the equator. + /// public readonly double Latitude; + + /// + /// Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England. + /// public readonly double Longitude; + + /// + /// The height above (positive) or below (negative) sea level, expressed in meters. + /// public readonly double Height; + /// + /// Creates an Observer object. + /// + /// Geographic latitude in degrees north (positive) or south (negative) of the equator. + /// Geographic longitude in degrees east (positive) or west (negative) of the prime meridian at Greenwich, England. + /// The height above (positive) or below (negative) sea level, expressed in meters. public Observer(double latitude, double longitude, double height) { Latitude = latitude; @@ -107,6 +251,9 @@ namespace CosineKitty } } + /// + /// The wrapper class that holds Astronomy Engine functions. + /// public static class Astronomy { private static readonly deltat_entry_t[] DT = new deltat_entry_t[] {