Fix `MathApi` formatting/documentation

sources/BaseRealm/API/Math/MathAPI.uc

@@ -1,6 +1,8 @@
 /**
- *  API that provides a collection of non-built in math methods used in Acedia.
+ * Author: dkanus
- *      Copyright 2022 Anton Tarasenko
+ * Home repo: https://www.insultplayers.ru/git/AcediaFramework/AcediaCore
+ * License: GPL
+ * Copyright 2020-2023 Anton Tarasenko
  *------------------------------------------------------------------------------
  * This file is part of Acedia.
  *
@@ -15,29 +17,21 @@
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
- * along with Acedia.  If not, see <https://www.gnu.org/licenses/>.
  */
 class MathAPI extends AcediaObject;
 
-/**
+//! API for basic math methods and [`BigInt`] creation.
- *  For storing result of integer division.
+
- *
+/// For storing result of integer division.
- *  If we divide `number` by `divisor`, then
+///
- *  `number = divisor * quotient + remainder`
+/// If we divide `number` by `divisor`, then `number = divisor/// quotient + remainder`.
- */
 struct IntegerDivisionResult
 {
     var int quotient;
     var int remainder;
 };
 
-/**
+/// Converts given [`int`] value into [`BigInt`] value..
- *  Changes current value of `BigInt` to given `BigInt` value.
- *
- *  @param  value   New value of the caller `BigInt`. If `none` is given,
- *      method does nothing.
- *  @return Self-reference to allow for method chaining.
- */
 public function BigInt ToBigInt(int value)
 {
     local BigInt result;
@@ -46,19 +40,13 @@ public function BigInt ToBigInt(int value)
     return result.SetInt(value);
 }
 
-/**
+
- *  Creates new `BigInt` value, base on the decimal representation given by
+/// Creates new `BigInt` value, based on the decimal number representation.
- *  `value`.
+///
- *
+/// Expects valid decimal representation as input (digits only, possibly with leading sign),
- *  If invalid decimal representation (digits only, possibly with leading sign)
+/// otherwise contents of returned value are undefined.
- *  is given - contents of returned value are undefined. Otherwise cannot fail.
+/// If invalid decimal representation is given - contents of returned value are undefined.
- *
+/// Otherwise cannot fail and is guaranteed to return non-`none` value.
- *  @param  value   New value of the caller `BigInt`, given by decimal
- *      its representation. If `none` is given, method returns `BigInt`
- *      containing `0` as value.
- *  @return Created `BigInt`, containing value, given by its the decimal
- *      representation `value`.
- */
 public function BigInt MakeBigInt(BaseText value)
 {
     local BigInt result;
@@ -67,18 +55,12 @@ public function BigInt MakeBigInt(BaseText value)
     return result.SetDecimal(value);
 }
 
-/**
+/// Creates new `BigInt` value, based on the decimal number representation.
- *  Creates new `BigInt` value, base on the decimal representation given by
+///
- *  `value`.
+/// Expects valid decimal representation as input (digits only, possibly with leading sign),
- *
+/// otherwise contents of returned value are undefined.
- *  If invalid decimal representation (digits only, possibly with leading sign)
+/// If invalid decimal representation is given - contents of returned value are undefined.
- *  is given - contents of returned value are undefined. Otherwise cannot fail.
+/// Otherwise cannot fail and is guaranteed to return non-`none` value.
- *
- *  @param  value   New value of the caller `BigInt`, given by decimal
- *      its representation.
- *  @return Created `BigInt`, containing value, given by its the decimal
- *      representation `value`.
- */
 public function BigInt MakeBigInt_S(string value)
 {
     local BigInt result;
@@ -87,42 +69,28 @@ public function BigInt MakeBigInt_S(string value)
     return result.SetDecimal_S(value);
 }
 
-/**
+/// Computes remainder of the integer division of [`number`] by [`divisor`].
- *  Computes remainder of the integer division of `number` by `divisor`.
+///
- *
+/// This method is necessary as a replacement for `%` module operator, since it is an operation on
- *  This method is necessary as a replacement for `%` module operator, since it
+/// `float`s in UnrealScript and does not have appropriate value range to work with big integer
- *  is an operation on `float`s in UnrealScript and does not have appropriate
+// values.
- *  value range to work with big integer values.
- *
- *  @see `IntegerDivision()` method if you need both quotient and remainder.
- *
- *  @param  number  Number that we are dividing.
- *  @param  divisor Number we are dividing by.
- *  @return Remainder of the integer division.
- */
 public function int Remainder(int number, int divisor)
 {
     local int quotient;
 
     quotient = number / divisor;
-    return (number - quotient * divisor);
+    return (number - quotient/// divisor);
 }
 
-/**
+/// Computes quotient and remainder of the integer division of [`number`] by [`divisor`].
- *  Computes quotient and remainder of the integer division of `number` by
+///
- *  `divisor`.
+/// See `MathApi::Remainder()` method if you only need remainder.
- *
- *  @see `IntegerDivision()` method if you only need remainder.
- *  @param  number  Number that we are dividing.
- *  @param  divisor Number we are dividing by.
- *  @return `struct` with quotient and remainder of the integer division.
- */
 public function IntegerDivisionResult IntegerDivision(int number, int divisor)
 {
     local IntegerDivisionResult result;
 
-    result.quotient     = number / divisor;
+    result.quotient = number / divisor;
-    result.remainder    = (number - result.quotient * divisor);
+    result.remainder = (number - result.quotient * divisor);
     return result;
 }