From 1bbea7dda0c96e65580474defe581885d59aa9a2 Mon Sep 17 00:00:00 2001
From: Felix Linker <linkerfelix@gmail.com>
Date: Thu, 23 Aug 2018 18:21:00 +0200
Subject: [PATCH] Improved docs

---
 src/app/components/Offence.jsx   | 22 +++++++++++-----------
 src/app/shipyard/Calculations.js | 32 ++++++++++++++++++++++++++++++--
 2 files changed, 41 insertions(+), 13 deletions(-)

diff --git a/src/app/components/Offence.jsx b/src/app/components/Offence.jsx
index 8f7abb36..83450bdf 100644
--- a/src/app/components/Offence.jsx
+++ b/src/app/components/Offence.jsx
@@ -44,9 +44,9 @@ export function weaponComparator(translate, propComparator, desc) {
 
 /**
  * Creates a tooltip that shows damage by type.
- * @param {function} translate  Translation function
- * @param {Object} formats      Object that holds format functions
- * @param {Object} sdpsObject   Object that holds sdps split up by type
+ * @param {function} translate    Translation function
+ * @param {Object} formats        Object that holds format functions
+ * @param {Calc.SDps} sdpsObject  Object that holds sdps split up by type
  * @returns {Array} Tooltip
  */
 function getSDpsTooltip(translate, formats, sdpsObject) {
@@ -62,9 +62,9 @@ function getSDpsTooltip(translate, formats, sdpsObject) {
 
 /**
  * Returns a data object used by {@link PieChart} that shows damage by type.
- * @param {function} translate  Translation function
- * @param {Object} sdpsObject   Object that holds sdps split up by type
- * @returns {Object}            Data object
+ * @param {function} translate    Translation function
+ * @param {Calc.SDps} sdpsObject  Object that holds sdps split up by type
+ * @returns {Object}              Data object
  */
 function getSDpsData(translate, sdpsObject) {
   return Object.keys(sdpsObject).map(key => {
@@ -77,8 +77,8 @@ function getSDpsData(translate, sdpsObject) {
 
 /**
  * Adds all damage of `add` onto `addOn`.
- * @param {Object} addOn  Object that holds sdps split up by type (will be mutated)
- * @param {Object} add    Object that holds sdps split up by type
+ * @param {Calc.SDps} addOn Object that holds sdps split up by type (will be mutated)
+ * @param {Calc.SDps} add   Object that holds sdps split up by type
  */
 function addSDps(addOn, add) {
   Object.keys(addOn).map(k => addOn[k] += (add[k] ? add[k] : 0));
@@ -86,7 +86,7 @@ function addSDps(addOn, add) {
 
 /**
  * Calculates the overall sdps of an sdps object.
- * @param {Object} sdpsObject   Object that holds sdps spluit up by type
+ * @param {Calc.SDps} sdpsObject Object that holds sdps spluit up by type
  */
 function sumSDps(sdpsObject) {
   if (sdpsObject.total) {
@@ -127,7 +127,7 @@ export default class Offence extends TranslatedComponent {
     this._sort = this._sort.bind(this);
 
     const damage = Calc.offenceMetrics(props.ship, props.opponent, props.wep, props.opponentSys, props.engagementrange);
-    this.state = { 
+    this.state = {
       predicate: 'n',
       desc: true,
       damage
@@ -247,7 +247,7 @@ export default class Offence extends TranslatedComponent {
           <td className='ri'><span onMouseOver={termtip.bind(null, effectiveArmourSDpsTooltipDetails)} onMouseOut={tooltip.bind(null, null)}>{formats.f1(weapon.sdps.armour.total)}</span></td>
           <td className='ri'><span onMouseOver={termtip.bind(null, effectivenessArmourTooltipDetails)} onMouseOut={tooltip.bind(null, null)}>{formats.pct1(weapon.effectiveness.armour.total)}</span></td>
         </tr>);
-    }    
+    }
 
     const totalSDps = sumSDps(totalSDpsObject);
     const totalSDpsTooltipDetails = getSDpsTooltip(translate, formats, totalSDpsObject);
diff --git a/src/app/shipyard/Calculations.js b/src/app/shipyard/Calculations.js
index 7fb348dd..d0cd0e2a 100644
--- a/src/app/shipyard/Calculations.js
+++ b/src/app/shipyard/Calculations.js
@@ -824,14 +824,42 @@ export function _sustainedDps(ship, opponent, opponentShields, opponentArmour, e
   return { shieldsdps, armoursdps, eps };
 }
 
+/**
+ * Stores SDPS split up by type.
+ * @typedef {Object} SDps
+ * @property {number} absolute  Damage of type absolute
+ * @property {number} explosive Damage of type explosive
+ * @property {number} kinetic   Damage of type kinetic
+ * @property {number} thermal   Damage of type thermal
+ * @property {number} [total]   Sum of all damage types
+ */
+
+/**
+ * An object that holds information about SDPS for a given weapon and opponent.
+ * @typedef {Object} WeaponDamage
+ * @property {number} eps           Energy per second
+ * @property {Object} damage        An object that stores damage inflicted by
+ *                                  the weapon.
+ * @property {Object} effectiveness An object that stores the effectiveness of
+ *                                  the weapon against the opponent given.
+ */
+
+/**
+ * Stores overall SDPS and against a given opponent's shields and armour.
+ * @typedef {Object} WeaponDamage~damage
+ * @property {SDps} base    Overall SDPS.
+ * @property {SDps} shields SDPS against the given opponent's shields.
+ * @property {SDps} armour  SDPS against the given opponent's armour.
+ */
+
 /**
  * Calculate the sustained DPS for a weapon at a given range
  * @param   {Object}  m                 The weapon
- * @param   {Object}  opponent        The opponent ship
+ * @param   {Object}  opponent          The opponent ship
  * @param   {Object}  opponentShields   The opponent's shield resistances
  * @param   {Object}  opponentArmour    The opponent's armour resistances
  * @param   {int}     engagementrange   The range between the ship and opponent
- * @returns {Object}                    Sustained DPS for shield and armour
+ * @returns {WeaponDamage}              Sustained DPS for shield and armour
  */
 export function _weaponSustainedDps(m, opponent, opponentShields, opponentArmour, engagementrange) {
   const opponentHasShields = opponentShields.generator ? true : false;