From 6be3117f6641e66877b1a0df1600cca20279dbea Mon Sep 17 00:00:00 2001 From: Christoph Ruegg Date: Wed, 18 Sep 2013 12:49:15 +0200 Subject: [PATCH] Trig: improve confusing/wrong inline docs and argument naming #138 --- src/Numerics/Trigonometry.cs | 612 +++++++++++------------------------ 1 file changed, 197 insertions(+), 415 deletions(-) diff --git a/src/Numerics/Trigonometry.cs b/src/Numerics/Trigonometry.cs index 9728d8c1..d509c66d 100644 --- a/src/Numerics/Trigonometry.cs +++ b/src/Numerics/Trigonometry.cs @@ -4,7 +4,7 @@ // http://github.com/mathnet/mathnet-numerics // http://mathnetnumerics.codeplex.com // -// Copyright (c) 2009-2010 Math.NET +// Copyright (c) 2009-2013 Math.NET // // Permission is hereby granted, free of charge, to any person // obtaining a copy of this software and associated documentation @@ -49,12 +49,8 @@ namespace MathNet.Numerics /// /// Converts a degree (360-periodic) angle to a grad (400-periodic) angle. /// - /// - /// The degree to convert. - /// - /// - /// The converted grad angle. - /// + /// The degree to convert. + /// The converted grad angle. public static double DegreeToGrad(double degree) { return degree * DegreeToGradConstant; @@ -63,12 +59,8 @@ namespace MathNet.Numerics /// /// Converts a degree (360-periodic) angle to a radian (2*Pi-periodic) angle. /// - /// - /// The degree to convert. - /// - /// - /// The converted radian angle. - /// + /// The degree to convert. + /// The converted radian angle. public static double DegreeToRadian(double degree) { return degree * Constants.Degree; @@ -77,12 +69,8 @@ namespace MathNet.Numerics /// /// Converts a grad (400-periodic) angle to a degree (360-periodic) angle. /// - /// - /// The grad to convert. - /// - /// - /// The converted degree. - /// + /// The grad to convert. + /// The converted degree. public static double GradToDegree(double grad) { return grad * 0.9; @@ -91,12 +79,8 @@ namespace MathNet.Numerics /// /// Converts a grad (400-periodic) angle to a radian (2*Pi-periodic) angle. /// - /// - /// The grad to convert. - /// - /// - /// The converted radian. - /// + /// The grad to convert. + /// The converted radian. public static double GradToRadian(double grad) { return grad * Constants.Grad; @@ -105,12 +89,8 @@ namespace MathNet.Numerics /// /// Converts a radian (2*Pi-periodic) angle to a degree (360-periodic) angle. /// - /// - /// The radian to convert. - /// - /// - /// The converted degree. - /// + /// The radian to convert. + /// The converted degree. public static double RadianToDegree(double radian) { return radian / Constants.Degree; @@ -119,26 +99,19 @@ namespace MathNet.Numerics /// /// Converts a radian (2*Pi-periodic) angle to a grad (400-periodic) angle. /// - /// - /// The radian to convert. - /// - /// - /// The converted grad. - /// + /// The radian to convert. + /// The converted grad. public static double RadianToGrad(double radian) { return radian / Constants.Grad; } + /// - /// Trigonometric Sine of an angle in radian + /// Trigonometric Sine of an angle in radian, or opposite / hypotenuse. /// - /// - /// The angle in radian. - /// - /// - /// The sine of the radian angle. - /// + /// The angle in radian. + /// The sine of the radian angle. public static double Sin(double radian) { return Math.Sin(radian); @@ -147,12 +120,8 @@ namespace MathNet.Numerics /// /// Trigonometric Sine of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The sine of the complex number. - /// + /// The complex value. + /// The sine of the complex number. public static Complex Sin(this Complex value) { if (value.IsReal()) @@ -166,14 +135,10 @@ namespace MathNet.Numerics } /// - /// Trigonometric Cosine of an angle in radian. + /// Trigonometric Cosine of an angle in radian, or adjacent / hypotenuse. /// - /// - /// The angle in radian. - /// - /// - /// The cosine of an angle in radian. - /// + /// The angle in radian. + /// The cosine of an angle in radian. public static double Cos(double radian) { return Math.Cos(radian); @@ -182,12 +147,8 @@ namespace MathNet.Numerics /// /// Trigonometric Cosine of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The cosine of a complex number. - /// + /// The complex value. + /// The cosine of a complex number. public static Complex Cos(this Complex value) { if (value.IsReal()) @@ -201,14 +162,10 @@ namespace MathNet.Numerics } /// - /// Trigonometric Tangent of an angle in radian + /// Trigonometric Tangent of an angle in radian, or opposite / adjacent. /// - /// - /// The angle in radian. - /// - /// - /// The tangent of the radian angle. - /// + /// The angle in radian. + /// The tangent of the radian angle. public static double Tan(double radian) { return Math.Tan(radian); @@ -217,12 +174,8 @@ namespace MathNet.Numerics /// /// Trigonometric Tangent of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The tangent of the complex number. - /// + /// The complex value. + /// The tangent of the complex number. public static Complex Tan(this Complex value) { if (value.IsReal()) @@ -238,14 +191,10 @@ namespace MathNet.Numerics } /// - /// Trigonometric Cotangent of an angle in radian. + /// Trigonometric Cotangent of an angle in radian, or adjacent / opposite. Reciprocal of the tangent. /// - /// - /// The angle in radian. - /// - /// - /// The cotangent of an angle in radian. - /// + /// The angle in radian. + /// The cotangent of an angle in radian. public static double Cot(double radian) { return 1 / Math.Tan(radian); @@ -254,12 +203,8 @@ namespace MathNet.Numerics /// /// Trigonometric Cotangent of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The cotangent of the complex number. - /// + /// The complex value. + /// The cotangent of the complex number. public static Complex Cot(this Complex value) { if (value.IsReal()) @@ -275,14 +220,10 @@ namespace MathNet.Numerics } /// - /// Trigonometric Secant of an angle in radian + /// Trigonometric Secant of an angle in radian, or hypotenuse / adjacent. Reciprocal of the cosine. /// - /// - /// The angle in radian. - /// - /// - /// The secant of the radian angle. - /// + /// The angle in radian. + /// The secant of the radian angle. public static double Sec(double radian) { return 1 / Math.Cos(radian); @@ -291,12 +232,8 @@ namespace MathNet.Numerics /// /// Trigonometric Secant of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The secant of the complex number. - /// + /// The complex value. + /// The secant of the complex number. public static Complex Sec(this Complex value) { if (value.IsReal()) @@ -312,14 +249,10 @@ namespace MathNet.Numerics } /// - /// Trigonometric Cosecant of an angle in radian. + /// Trigonometric Cosecant of an angle in radian, or hypotenuse / opposite. Reciprocal of the sine. /// - /// - /// The angle in radian. - /// - /// - /// Cosecant of an angle in radian. - /// + /// The angle in radian. + /// Cosecant of an angle in radian. public static double Csc(double radian) { return 1 / Math.Sin(radian); @@ -328,12 +261,8 @@ namespace MathNet.Numerics /// /// Trigonometric Cosecant of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The cosecant of a complex number. - /// + /// The complex value. + /// The cosecant of a complex number. public static Complex Csc(this Complex value) { if (value.IsReal()) @@ -348,29 +277,22 @@ namespace MathNet.Numerics return new Complex(sinr * Cosh(value.Imaginary) / denom, -Cos(value.Real) * sinhi / denom); } + /// - /// Trigonometric Arc Sine in radian + /// Trigonometric principal Arc Sine in radian /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse sine of the radian angle. - /// - public static double Asin(double radian) + /// The opposite for a unit hypotenuse (i.e. opposite / hyptenuse). + /// The angle in radian. + public static double Asin(double opposite) { - return Math.Asin(radian); + return Math.Asin(opposite); } /// - /// Trigonometric Arc Sine of this Complex number. + /// Trigonometric principal Arc Sine of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The arc sine of a complex number. - /// + /// The complex value. + /// The arc sine of a complex number. public static Complex Asin(this Complex value) { if (value.Imaginary > 0 || value.Imaginary == 0d && value.Real < 0) @@ -382,31 +304,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Arc Cosine in radian + /// Trigonometric principal Arc Cosine in radian /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse cosine of the radian angle. - /// - /// - /// if 1 < or < -1. - /// - public static double Acos(double radian) + /// The adjacent for a unit hypotenuse (i.e. adjacent / hypotenuse). + /// The angle in radian. + public static double Acos(double adjacent) { - return Math.Acos(radian); + return Math.Acos(adjacent); } /// - /// Trigonometric Arc Cosine of this Complex number. + /// Trigonometric principal Arc Cosine of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The arc cosine of a complex number. - /// + /// The complex value. + /// The arc cosine of a complex number. public static Complex Acos(this Complex value) { if (value.Imaginary < 0 || value.Imaginary == 0d && value.Real > 0) @@ -418,28 +329,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Arc Tangent in radian + /// Trigonometric principal Arc Tangent in radian /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse tangent of the radian angle. - /// - public static double Atan(double radian) + /// The opposite for a unit adjacent (i.e. opposite / adjacent). + /// The angle in radian. + public static double Atan(double opposite) { - return Math.Atan(radian); + return Math.Atan(opposite); } /// - /// Trigonometric Arc Tangent of this Complex number. + /// Trigonometric principal Arc Tangent of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The arc tangent of a complex number. - /// + /// The complex value. + /// The arc tangent of a complex number. public static Complex Atan(this Complex value) { var iz = new Complex(-value.Imaginary, value.Real); // I*this @@ -447,28 +350,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Arc Cotangent in radian + /// Trigonometric principal Arc Cotangent in radian /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse cotangent of the radian angle. - /// - public static double Acot(double radian) + /// The adjacent for a unit opposite (i.e. adjacent / opposite). + /// The angle in radian. + public static double Acot(double adjacent) { - return Math.Atan(1 / radian); + return Math.Atan(1 / adjacent); } /// - /// Trigonometric Arc Cotangent of this Complex number. + /// Trigonometric principal Arc Cotangent of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The arc cotangent of a complex number. - /// + /// The complex value. + /// The arc cotangent of a complex number. public static Complex Acot(this Complex value) { if (value.IsZero()) @@ -481,28 +376,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Arc Secant in radian + /// Trigonometric principal Arc Secant in radian /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse secant of the radian angle. - /// - public static double Asec(double radian) + /// The hypotenuse for a unit adjacent (i.e. hypotenuse / adjacent). + /// The angle in radian. + public static double Asec(double hypotenuse) { - return Math.Acos(1 / radian); + return Math.Acos(1 / hypotenuse); } /// - /// Trigonometric Arc Secant of this Complex number. + /// Trigonometric principal Arc Secant of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The arc secant of a complex number. - /// + /// The complex value. + /// The arc secant of a complex number. public static Complex Asec(this Complex value) { var inv = 1 / value; @@ -510,60 +397,42 @@ namespace MathNet.Numerics } /// - /// Trigonometric Arc Cosecant in radian + /// Trigonometric principal Arc Cosecant in radian /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse cosecant of the radian angle. - /// - /// - /// if -1 < < 1. - /// - public static double Acsc(double radian) + /// The hypotenuse for a unit opposite (i.e. hypotenuse / opposite). + /// The angle in radian. + public static double Acsc(double hypotenuse) { - return Math.Asin(1 / radian); + return Math.Asin(1 / hypotenuse); } /// - /// Trigonometric Arc Cosecant of this Complex number. + /// Trigonometric principal Arc Cosecant of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The arc cosecant of a complex number. - /// + /// The complex value. + /// The arc cosecant of a complex number. public static Complex Acsc(this Complex value) { var inv = 1 / value; return -Complex.ImaginaryOne * ((Complex.ImaginaryOne * inv) + (1 - inv.Square()).SquareRoot()).Ln(); } + /// - /// Trigonometric Hyperbolic Sine + /// Hyperbolic Sine /// - /// - /// The angle in radian angle. - /// - /// - /// The hyperbolic sine of the radian angle. - /// - public static double Sinh(double radian) + /// The hyperbolic angle, i.e. the area of the hyperbolic sector. + /// The hyperbolic sine of the angle. + public static double Sinh(double angle) { - return (Math.Exp(radian) - Math.Exp(-radian)) / 2; + return (Math.Exp(angle) - Math.Exp(-angle)) / 2; } /// - /// Trigonometric Hyperbolic Sine of a Complex number. + /// Hyperbolic Sine of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic sine of a complex number. - /// + /// The complex value. + /// The hyperbolic sine of a complex number. public static Complex Sinh(this Complex value) { if (value.IsReal()) @@ -577,28 +446,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Hyperbolic Cosine + /// Hyperbolic Cosine /// - /// - /// The angle in radian. - /// - /// - /// The hyperbolic Cosine of the radian angle. - /// - public static double Cosh(double radian) + /// The hyperbolic angle, i.e. the area of the hyperbolic sector. + /// The hyperbolic Cosine of the angle. + public static double Cosh(double angle) { - return (Math.Exp(radian) + Math.Exp(-radian)) / 2; + return (Math.Exp(angle) + Math.Exp(-angle)) / 2; } /// - /// Trigonometric Hyperbolic Cosine of a Complex number. + /// Hyperbolic Cosine of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic cosine of a complex number. - /// + /// The complex value. + /// The hyperbolic cosine of a complex number. public static Complex Cosh(this Complex value) { if (value.IsReal()) @@ -612,40 +473,32 @@ namespace MathNet.Numerics } /// - /// Trigonometric Hyperbolic Tangent in radian + /// Hyperbolic Tangent in radian /// - /// - /// The angle in radian angle. - /// - /// - /// The hyperbolic tangent of the radian angle. - /// - public static double Tanh(double radian) + /// The hyperbolic angle, i.e. the area of the hyperbolic sector. + /// The hyperbolic tangent of the angle. + public static double Tanh(double angle) { - if (radian > 19.1) + if (angle > 19.1) { return 1.0; } - if (radian < -19.1) + if (angle < -19.1) { return -1; } - var e1 = Math.Exp(radian); - var e2 = Math.Exp(-radian); + var e1 = Math.Exp(angle); + var e2 = Math.Exp(-angle); return (e1 - e2) / (e1 + e2); } /// - /// Trigonometric Hyperbolic Tangent of a Complex number. + /// Hyperbolic Tangent of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic tangent of a complex number. - /// + /// The complex value. + /// The hyperbolic tangent of a complex number. public static Complex Tanh(this Complex value) { if (value.IsReal()) @@ -667,40 +520,32 @@ namespace MathNet.Numerics } /// - /// Trigonometric Hyperbolic Cotangent + /// Hyperbolic Cotangent /// - /// - /// The angle in radian angle. - /// - /// - /// The hyperbolic cotangent of the radian angle. - /// - public static double Coth(double radian) + /// The hyperbolic angle, i.e. the area of the hyperbolic sector. + /// The hyperbolic cotangent of the angle. + public static double Coth(double angle) { - if (radian > 19.115) + if (angle > 19.115) { return 1.0; } - if (radian < -19.115) + if (angle < -19.115) { return -1; } - var e1 = Math.Exp(radian); - var e2 = Math.Exp(-radian); + var e1 = Math.Exp(angle); + var e2 = Math.Exp(-angle); return (e1 + e2) / (e1 - e2); } /// - /// Trigonometric Hyperbolic Cotangent of a Complex number. + /// Hyperbolic Cotangent of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic cotangent of a complex number. - /// + /// The complex value. + /// The hyperbolic cotangent of a complex number. public static Complex Coth(this Complex value) { if (value.IsReal()) @@ -722,28 +567,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Hyperbolic Secant + /// Hyperbolic Secant /// - /// - /// The angle in radian angle. - /// - /// - /// The hyperbolic secant of the radian angle. - /// - public static double Sech(double radian) + /// The hyperbolic angle, i.e. the area of the hyperbolic sector. + /// The hyperbolic secant of the angle. + public static double Sech(double angle) { - return 1 / Cosh(radian); + return 1 / Cosh(angle); } /// - /// Trigonometric Hyperbolic Secant of a Complex number. + /// Hyperbolic Secant of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic secant of a complex number. - /// + /// The complex value. + /// The hyperbolic secant of a complex number. public static Complex Sech(this Complex value) { if (value.IsReal()) @@ -762,28 +599,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Hyperbolic Cosecant + /// Hyperbolic Cosecant /// - /// - /// The angle in radian. - /// - /// - /// The hyperbolic cosecant of the radian angle. - /// - public static double Csch(double radian) + /// The hyperbolic angle, i.e. the area of the hyperbolic sector. + /// The hyperbolic cosecant of the angle. + public static double Csch(double angle) { - return 1 / Sinh(radian); + return 1 / Sinh(angle); } /// - /// Trigonometric Hyperbolic Cosecant of a Complex number. + /// Hyperbolic Cosecant of a Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic cosecant of a complex number. - /// + /// The complex value. + /// The hyperbolic cosecant of a complex number. public static Complex Csch(this Complex value) { if (value.IsReal()) @@ -801,113 +630,82 @@ namespace MathNet.Numerics return 2 * exp / (exp.Square() - 1); } + /// - /// Trigonometric Hyperbolic Area Sine + /// Hyperbolic Area Sine /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse hyperbolic sine of the radian angle. - /// - public static double Asinh(double radian) + /// The real value. + /// The hyperbolic angle, i.e. the area of its hyperbolic sector. + public static double Asinh(double value) { - return Math.Log(radian + Math.Sqrt((radian * radian) + 1), Math.E); + return Math.Log(value + Math.Sqrt((value * value) + 1), Math.E); } /// - /// Trigonometric Hyperbolic Arc Sine of this Complex number. + /// Hyperbolic Area Sine of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic arc sine of a complex number. - /// + /// The complex value. + /// The hyperbolic arc sine of a complex number. public static Complex Asinh(this Complex value) { return (value + (value.Square() + 1).SquareRoot()).Ln(); } /// - /// Trigonometric Hyperbolic Area Cosine + /// Hyperbolic Area Cosine /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse hyperbolic cosine of the radian angle. - /// - public static double Acosh(double radian) + /// The real value. + /// The hyperbolic angle, i.e. the area of its hyperbolic sector. + public static double Acosh(double value) { - return Math.Log(radian + (Math.Sqrt(radian - 1) * Math.Sqrt(radian + 1)), Math.E); + return Math.Log(value + (Math.Sqrt(value - 1) * Math.Sqrt(value + 1)), Math.E); } /// - /// Trigonometric Hyperbolic Arc Cosine of this Complex number. + /// Hyperbolic Area Cosine of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic arc cosine of a complex number. - /// + /// The complex value. + /// The hyperbolic arc cosine of a complex number. public static Complex Acosh(this Complex value) { return (value + ((value - 1).SquareRoot() * (value + 1).SquareRoot())).Ln(); } /// - /// Trigonometric Hyperbolic Area Tangent + /// Hyperbolic Area Tangent /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse hyperbolic tangent of the radian angle. - /// - public static double Atanh(double radian) + /// The real value. + /// The hyperbolic angle, i.e. the area of its hyperbolic sector. + public static double Atanh(double value) { - return 0.5 * Math.Log((1 + radian) / (1 - radian), Math.E); + return 0.5 * Math.Log((1 + value) / (1 - value), Math.E); } /// - /// Trigonometric Hyperbolic Arc Tangent of this Complex number. + /// Hyperbolic Area Tangent of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic arc tangent of a complex number. - /// + /// The complex value. + /// The hyperbolic arc tangent of a complex number. public static Complex Atanh(this Complex value) { return 0.5 * ((1 + value).Ln() - (1 - value).Ln()); } /// - /// Trigonometric Hyperbolic Arc Cotangent + /// Hyperbolic Area Cotangent /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse hyperbolic cotangent of the radian angle. - /// - public static double Acoth(double radian) + /// The real value. + /// The hyperbolic angle, i.e. the area of its hyperbolic sector. + public static double Acoth(double value) { - return 0.5 * Math.Log((radian + 1) / (radian - 1), Math.E); + return 0.5 * Math.Log((value + 1) / (value - 1), Math.E); } /// - /// Trigonometric Hyperbolic Arc Cotangent of this Complex number. + /// Hyperbolic Area Cotangent of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic arc cotangent of a complex number. - /// + /// The complex value. + /// The hyperbolic arc cotangent of a complex number. public static Complex Acoth(this Complex value) { var inv = 1.0 / value; @@ -915,28 +713,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Hyperbolic Area Secant + /// Hyperbolic Area Secant /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse hyperbolic secant of the radian angle. - /// - public static double Asech(double radian) + /// The real value. + /// The hyperbolic angle, i.e. the area of its hyperbolic sector. + public static double Asech(double value) { - return Acosh(1 / radian); + return Acosh(1 / value); } /// - /// Trigonometric Hyperbolic Arc Secant of this Complex number. + /// Hyperbolic Area Secant of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic arc secant of a complex number. - /// + /// The complex value. + /// The hyperbolic arc secant of a complex number. public static Complex Asech(this Complex value) { var inv = 1 / value; @@ -944,28 +734,20 @@ namespace MathNet.Numerics } /// - /// Trigonometric Hyperbolic Arc Cosecant + /// Hyperbolic Area Cosecant /// - /// - /// The angle in radian angle. - /// - /// - /// The inverse hyperbolic cosecant of the radian angle. - /// - public static double Acsch(double radian) + /// The real value. + /// The hyperbolic angle, i.e. the area of its hyperbolic sector. + public static double Acsch(double value) { - return Asinh(1 / radian); + return Asinh(1 / value); } /// - /// Trigonometric Hyperbolic Arc Cosecant of this Complex number. + /// Hyperbolic Area Cosecant of this Complex number. /// - /// - /// The complex value. - /// - /// - /// The hyperbolic arc cosecant of a complex number. - /// + /// The complex value. + /// The hyperbolic arc cosecant of a complex number. public static Complex Acsch(this Complex value) { var inv = 1 / value;