From ca767ece3953cb3bdf7886359cc5ebd3e4156f93 Mon Sep 17 00:00:00 2001 From: Jim Carr Date: Sun, 21 Feb 2021 15:32:50 -0500 Subject: [PATCH] Added additional .csproj tags and additional documentation comments to support the NuGet package. --- PALib/Data/BinaryData.cs | 10 ++++ PALib/Data/CometData.cs | 81 +++++++++++++++++++++++++++++++++ PALib/Data/PlanetData.cs | 58 +++++++++++++++++++++++ PALib/Helpers/MathExtensions.cs | 7 ++- PALib/PABinary.cs | 3 ++ PALib/PAComet.cs | 3 ++ PALib/PACoordinates.cs | 3 ++ PALib/PADateTime.cs | 3 ++ PALib/PAEclipses.cs | 3 ++ PALib/PALib.csproj | 16 +++++-- PALib/PAMacros.cs | 3 ++ PALib/PAMoon.cs | 3 ++ PALib/PAPlanet.cs | 3 ++ PALib/PASun.cs | 9 ++-- PALib/PATypes.cs | 48 +++++++++++++++++++ PALib/PAUtils.cs | 3 ++ README.md | 42 +++++++++++++++++ 17 files changed, 288 insertions(+), 10 deletions(-) diff --git a/PALib/Data/BinaryData.cs b/PALib/Data/BinaryData.cs index 4900485..e35c01f 100644 --- a/PALib/Data/BinaryData.cs +++ b/PALib/Data/BinaryData.cs @@ -3,6 +3,9 @@ namespace PALib.Data { + /// + /// Holds information about binary star systems. + /// public class BinaryData { /// @@ -46,6 +49,9 @@ public class BinaryData public double PANode { get; set; } } + /// + /// Binary star system data manager. + /// public static class BinaryInfo { static List _binaryData; @@ -157,6 +163,10 @@ static BinaryInfo() }; } + /// + /// Retrieve information about a specific binary star system. + /// + /// public static BinaryData GetBinaryInfo(string name) { var returnValue = _binaryData diff --git a/PALib/Data/CometData.cs b/PALib/Data/CometData.cs index 8590e6d..bcaee19 100644 --- a/PALib/Data/CometData.cs +++ b/PALib/Data/CometData.cs @@ -3,30 +3,101 @@ namespace PALib.Data { + /// + /// Information about a comet with an elliptical orbit. + /// public class CometDataElliptical { + /// + /// Name of comet + /// public string Name { get; set; } + + /// + /// Epoch of the perihelion + /// public double epoch_EpochOfPerihelion { get; set; } + + /// + /// Longitude of the perihelion + /// public double peri_LongitudeOfPerihelion { get; set; } + + /// + /// Longitude of the ascending node + /// public double node_LongitudeOfAscendingNode { get; set; } + + /// + /// Period of the orbit + /// public double period_PeriodOfOrbit { get; set; } + + /// + /// Semi-major axis of the orbit + /// public double axis_SemiMajorAxisOfOrbit { get; set; } + + /// + /// Eccentricity of the orbit + /// public double ecc_EccentricityOfOrbit { get; set; } + + /// + /// Inclination of the orbit + /// public double incl_InclinationOfOrbit { get; set; } } + /// + /// Information about a comet with a parabolic orbit. + /// public class CometDataParabolic { + /// + /// Name of the comet + /// public string Name { get; set; } + + /// + /// Epoch perihelion day + /// public double EpochPeriDay { get; set; } + + /// + /// Epoch perihelion month + /// public int EpochPeriMonth { get; set; } + + /// + /// Epoch perihelion year + /// public int EpochPeriYear { get; set; } + + /// + /// Arg perihelion + /// public double ArgPeri { get; set; } + + /// + /// Comet's node + /// public double Node { get; set; } + + /// + /// Distance at the perihelion + /// public double PeriDist { get; set; } + + /// + /// Inclination + /// public double Incl { get; set; } } + /// + /// Data manager for comets with elliptical orbits. + /// public static class CometInfoElliptical { static List _cometDataElliptical; @@ -188,6 +259,9 @@ static CometInfoElliptical() }; } + /// + /// Get information about a comet with an elliptical orbit. + /// public static CometDataElliptical GetCometEllipticalInfo(string name) { var returnValue = _cometDataElliptical @@ -198,6 +272,10 @@ public static CometDataElliptical GetCometEllipticalInfo(string name) return (returnValue == null) ? new CometDataElliptical() { Name = "NotFound" } : returnValue; } } + + /// + /// Data manager for comets with parabolic orbits. + /// public static class CometInfoParabolic { static List _cometDataParabolic; @@ -218,6 +296,9 @@ static CometInfoParabolic() }; } + /// + /// Get information about a comet with a parabolic orbit. + /// public static CometDataParabolic GetCometParabolicInfo(string name) { var returnValue = _cometDataParabolic diff --git a/PALib/Data/PlanetData.cs b/PALib/Data/PlanetData.cs index 417f208..3ffe72e 100644 --- a/PALib/Data/PlanetData.cs +++ b/PALib/Data/PlanetData.cs @@ -3,8 +3,14 @@ namespace PALib.Data { + /// + /// Information about a planet. + /// public class PlanetData { + /// + /// Name of planet. + /// public string Name { get; set; } /// @@ -89,21 +95,70 @@ public class PlanetData public double v0_VisualMagnitude { get; set; } } + /// + /// Working data for precise planet calculations. + /// public class PlanetDataPrecise { + /// + /// Name of planet. + /// public string Name { get; set; } + + /// + /// Working value 1. + /// public double Value1 { get; set; } + + /// + /// Working value 2. + /// public double Value2 { get; set; } + + /// + /// Working value 3. + /// public double Value3 { get; set; } + + /// + /// Working value 4. + /// public double Value4 { get; set; } + + /// + /// Working value 5. + /// public double Value5 { get; set; } + + /// + /// Working value 6. + /// public double Value6 { get; set; } + + /// + /// Working value 7. + /// public double Value7 { get; set; } + + /// + /// Working value 8. + /// public double Value8 { get; set; } + + /// + /// Working value 9. + /// public double Value9 { get; set; } + + /// + /// Working AP value. + /// public double APValue { get; set; } } + /// + /// Data manager for planets. + /// public static class PlanetInfo { static List _planetData; @@ -210,6 +265,9 @@ static PlanetInfo() }; } + /// + /// Get information about a planet. + /// public static PlanetData GetPlanetInfo(string name) { var returnValue = _planetData diff --git a/PALib/Helpers/MathExtensions.cs b/PALib/Helpers/MathExtensions.cs index f597c88..0f91278 100644 --- a/PALib/Helpers/MathExtensions.cs +++ b/PALib/Helpers/MathExtensions.cs @@ -2,6 +2,9 @@ namespace PALib.Helpers { + /// + /// Extension methods for mathematical calculations. + /// public static class MathExtensions { /// @@ -48,8 +51,6 @@ public static double ASine(this double d) /// /// Returns the cosine of the specified angle. /// - /// - /// public static double Cosine(this double d) { return Math.Cos(d); @@ -79,8 +80,6 @@ public static double Log10(this double d) /// /// Returns the sine of the specified angle. /// - /// - /// public static double Sine(this double a) { return Math.Sin(a); diff --git a/PALib/PABinary.cs b/PALib/PABinary.cs index 12b4a93..4444ee9 100644 --- a/PALib/PABinary.cs +++ b/PALib/PABinary.cs @@ -4,6 +4,9 @@ namespace PALib { + /// + /// Binary star calculations. + /// public class PABinary { /// diff --git a/PALib/PAComet.cs b/PALib/PAComet.cs index e65d8e0..37739c7 100644 --- a/PALib/PAComet.cs +++ b/PALib/PAComet.cs @@ -4,6 +4,9 @@ namespace PALib { + /// + /// Comet calculations. + /// public class PAComet { /// diff --git a/PALib/PACoordinates.cs b/PALib/PACoordinates.cs index 8b3f636..77e281f 100644 --- a/PALib/PACoordinates.cs +++ b/PALib/PACoordinates.cs @@ -3,6 +3,9 @@ namespace PALib { + /// + /// Coordinate system calculations and conversions. + /// public class PACoordinates { /// diff --git a/PALib/PADateTime.cs b/PALib/PADateTime.cs index 2495449..33e27a4 100644 --- a/PALib/PADateTime.cs +++ b/PALib/PADateTime.cs @@ -3,6 +3,9 @@ namespace PALib { + /// + /// Date and time calculations. + /// public class PADateTime { /// diff --git a/PALib/PAEclipses.cs b/PALib/PAEclipses.cs index 23c6052..c23209c 100644 --- a/PALib/PAEclipses.cs +++ b/PALib/PAEclipses.cs @@ -3,6 +3,9 @@ namespace PALib { + /// + /// Eclipse calculations. + /// public class PAEclipses { /// diff --git a/PALib/PALib.csproj b/PALib/PALib.csproj index 563e6f9..456f4d9 100644 --- a/PALib/PALib.csproj +++ b/PALib/PALib.csproj @@ -1,7 +1,17 @@ - - net5.0 - + + net5.0 + true + PracticalAstronomyDotNet + 1.0.2 + Jim Carr + Good Guy Science + Algorithms from "Practical Astronomy with your Calculator or Spreadsheet" + + This library contains an implementation of the algorithms from the "Practical Astronomy with your Calculator or Spreadsheet" book, authored by Peter Duffet-Smith and Jonathan Zwart. + + https://github.com/jfcarr-astronomy/practical-astronomy-dotnet + diff --git a/PALib/PAMacros.cs b/PALib/PAMacros.cs index d31db43..76f480c 100644 --- a/PALib/PAMacros.cs +++ b/PALib/PAMacros.cs @@ -6,6 +6,9 @@ namespace PALib { + /// + /// Miscellaneous macro functions supporting the other classes. + /// public static class PAMacros { /// diff --git a/PALib/PAMoon.cs b/PALib/PAMoon.cs index f7c2c31..9985741 100644 --- a/PALib/PAMoon.cs +++ b/PALib/PAMoon.cs @@ -3,6 +3,9 @@ namespace PALib { + /// + /// Moon calculations. + /// public class PAMoon { /// diff --git a/PALib/PAPlanet.cs b/PALib/PAPlanet.cs index 9f40d06..0fcde3d 100644 --- a/PALib/PAPlanet.cs +++ b/PALib/PAPlanet.cs @@ -4,6 +4,9 @@ namespace PALib { + /// + /// Planet calculations. + /// public class PAPlanet { /// diff --git a/PALib/PASun.cs b/PALib/PASun.cs index daef6cb..f40b09a 100644 --- a/PALib/PASun.cs +++ b/PALib/PASun.cs @@ -3,6 +3,9 @@ namespace PALib { + /// + /// Sun calculations. + /// public class PASun { /// @@ -197,9 +200,9 @@ public class PASun /// /// Calculate the equation of time. (The difference between the real Sun time and the mean Sun time.) /// - /// Greenwich date (day part) - /// Greenwich date (month part) - /// Greenwich date (year part) + /// Greenwich date (day part) + /// Greenwich date (month part) + /// Greenwich date (year part) /// /// equation_of_time_min -- equation of time (minute part) /// equation_of_time_sec -- equation of time (seconds part) diff --git a/PALib/PATypes.cs b/PALib/PATypes.cs index bc6c940..ba71ba6 100644 --- a/PALib/PATypes.cs +++ b/PALib/PATypes.cs @@ -1,9 +1,19 @@ using System; namespace PALib { + /// + /// Coordinate types + /// public enum PACoordinateType { + /// + /// Apparent (observer) + /// Apparent, + + /// + /// Actual/real + /// True } @@ -15,14 +25,35 @@ public enum PACoordinateType /// public enum PATwilightType { + /// + /// First period of twilight. + /// Civil = 6, + + /// + /// Second period of twilight. + /// Nautical = 12, + + /// + /// Second period of twilight. + /// Astronomical = 18 } + /// + /// Angle measurement units. + /// public enum PAAngleMeasure { + /// + /// Measurement by degrees. + /// Degrees, + + /// + /// Measurement by hours. + /// Hours } @@ -31,13 +62,30 @@ public enum PAAngleMeasure /// public enum PAAccuracyLevel { + /// + /// Approximate value. + /// Approximate, + + /// + /// Precise value. + /// Precise } + /// + /// Warning flags for calculation results. + /// public enum PAWarningFlag { + /// + /// Calculation result is OK. + /// OK, + + /// + /// Calculation result is invalid/inaccurate. + /// Warning } } \ No newline at end of file diff --git a/PALib/PAUtils.cs b/PALib/PAUtils.cs index 5b087f9..a7c5f47 100644 --- a/PALib/PAUtils.cs +++ b/PALib/PAUtils.cs @@ -1,6 +1,9 @@ using System; namespace PALib { + /// + /// Utility methods. + /// public static class PAUtils { /// diff --git a/README.md b/README.md index aed7147..e6ce3f0 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,48 @@ Algorithms from "[Practical Astronomy with your Calculator or Spreadsheet](https If you're interested in this topic, please buy the book! It provides far more detail and context. +## Getting Started (for clients) + +Create a console application: + +```bash +dotnet new console -o PAConsoleTest + +cd PAConsoleTest +``` + +Using the NuGet package is the easiest way to consume the library in a client application. Add a NuGet reference for the Practical Astronomy library, following the directions [here](https://www.nuget.org/packages/PracticalAstronomyDotNet/). + +Open Program.cs, and make a few changes. First, add a `using` statement for Practical Astronomy: + +```csharp +using PALib; +``` + +Then, replace the 'Hello World' boilerplate with this: + +```csharp +// Coordinates test (angle degrees to decimal degrees) +var paCoordinates = new PALib.PACoordinates(); + +var decimalDegrees = Math.Round(paCoordinates.AngleToDecimalDegrees(182, 31, 27), 3); + +Console.WriteLine($"Decimal degrees value is {decimalDegrees}"); + +// Moon test (approximate moon phase) +var paMoon = new PALib.PAMoon(); + +var (moonPhase, brightLimbDegrees) = paMoon.MoonPhase(0, 0, 0, false, 0, 1, 9, 2003, PAAccuracyLevel.Approximate); + +Console.WriteLine($"Moon phase value is {moonPhase}, bright limb degrees value is {brightLimbDegrees}"); +``` + +When you run, you should see this: + +``` +Decimal degrees value is 182.524 +Moon phase value is 0.22, bright limb degrees value is -71.58 +``` ## Library Functions - Status ### Date/Time