Improved docs

src/app/components/Offence.jsx

@@ -46,7 +46,7 @@ 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 {Calc.SDps} sdpsObject  Object that holds sdps split up by type
  * @returns {Array} Tooltip
  */
 function getSDpsTooltip(translate, formats, sdpsObject) {
@@ -63,7 +63,7 @@ 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
+ * @param {Calc.SDps} sdpsObject  Object that holds sdps split up by type
  * @returns {Object}              Data object
  */
 function getSDpsData(translate, sdpsObject) {
@@ -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) {

src/app/shipyard/Calculations.js

@@ -824,6 +824,34 @@ 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
@@ -831,7 +859,7 @@ export function _sustainedDps(ship, opponent, opponentShields, opponentArmour, e
  * @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;