Merge pull request #49 from jhwohlgemuth/feature/flow-enhancements

Add JSDoc support (post-flow) and improve some flow annotations

Gruntfile.js

@@ -18,6 +18,7 @@ module.exports = function (grunt) {
                 src: ['./lib/**/*.js'],
                 dest: './docs',
                 options: {
+                    configure: './jsdoc.conf.js',
                     readme: 'README.md',
                     template: 'node_modules/minami'
                 }

docs/atmosphere.js.html

@@ -39,7 +39,8 @@ <h1 class="page-title">atmosphere.js</h1>
 
     <section>
         <article>
-            <pre class="prettyprint source linenums"><code>/**
+            <pre class="prettyprint source linenums"><code>// @flow
+/**
  * @file Atmospheric, thermodynamic, and aerodynamic
  * @description Uses a combination of US Standard Atmospheres for 1962 and 1976
  * @author Jason Wohlgemuth
@@ -48,7 +49,6 @@ <h1 class="page-title">atmosphere.js</h1>
  * (pages 226, 228-229)
  * [citation]{@link https://dl.acm.org/citation.cfm?id=1534352&amp;preflayout=flat}
 **/
-'use strict';
 
 const partial  = require('lodash/partial');
 const lte      = require('lodash/lte');
@@ -97,7 +97,7 @@ <h1 class="page-title">atmosphere.js</h1>
  * @param {number} altitude Altitude (in km)
  * @returns {string} The name of the strata that contains the altitude
 **/
-function getStrata(altitude) {
+function getStrata(altitude: number): string {
     return findKey(ATMOSPHERIC_STRATA, (val) => {
         return val[0] &lt;= altitude &amp;&amp; altitude &lt;= val[1];
     });
@@ -107,7 +107,7 @@ <h1 class="page-title">atmosphere.js</h1>
  * @param {number} i Refers to the quantities at the base of the layer
  * @returns {number} molecular weight (in g/mole)
 **/
-function molecularWeight(i) {
+function molecularWeight(i: number): number {
     const MOLECULAR_WEIGHT_AT_SEA_LEVEL = 28.964;
     const M = [/* eslint-disable no-magic-numbers */
         MOLECULAR_WEIGHT_AT_SEA_LEVEL,
@@ -142,7 +142,7 @@ <h1 class="page-title">atmosphere.js</h1>
  * @param {number} i Refers to the quantities at the base of the layer
  * @returns {number} altitude (in meters)
 **/
-function h(i) {
+function h(i: number): number {
     const h = [/* eslint-disable no-magic-numbers */
         0,
         11019.1,
@@ -168,7 +168,7 @@ <h1 class="page-title">atmosphere.js</h1>
     ];/* eslint-enable no-magic-numbers */
     return h[i];
 }
-function getLayerIndex(altitude) {
+function getLayerIndex(altitude: number) {
     let inLayer = partial(lte, altitude);
     return range(NUMBER_OF_LAYERS)
         .map(h)
@@ -181,7 +181,7 @@ <h1 class="page-title">atmosphere.js</h1>
  * @param {number} i Refers to the quantities at the base of the layer
  * @returns {number} temperature (in K)
 **/
-function temperature(i) {
+function temperature(i: number): number {
     const T = [/* eslint-disable no-magic-numbers */
         288.15,
         216.65,
@@ -214,7 +214,7 @@ <h1 class="page-title">atmosphere.js</h1>
  * @param {number} i Refers to the quantities at the base of the layer
  * @returns {number} rate (in K/km)
 **/
-function a(i) {
+function a(i: number): number {
     const lapseRates = [/* eslint-disable no-magic-numbers */
         -6.5,
         0,
@@ -244,21 +244,21 @@ <h1 class="page-title">atmosphere.js</h1>
  * @function getMolecularTemperature
  * @param {number} altitude
 **/
-function getMolecularTemperature(altitude) {
-    let i = getLayerIndex(altitude);
+function getMolecularTemperature(altitude: number): number {
+    const i = getLayerIndex(altitude);
     return temperature(i) + (a(i) * (altitude - h(i)));
 }
 /**
  * @function getKineticTemperature
  * @param {number} altitude
 **/
-function getKineticTemperature(altitude) {
-    let i = getLayerIndex(altitude);
-    let Mo = molecularWeight(0);
-    let dM = delta(molecularWeight);
-    let dh = delta(h);
-    let Tm = getMolecularTemperature(altitude, i);
-    let ratio = molecularWeight(i) + ((dM(i + 1, i) * (altitude - h(i))) / dh(i + 1, i));
+function getKineticTemperature(altitude: number): number {
+    const i = getLayerIndex(altitude);
+    const Mo = molecularWeight(0);
+    const dM = delta(molecularWeight);
+    const dh = delta(h);
+    const Tm = getMolecularTemperature(altitude);
+    const ratio = molecularWeight(i) + ((dM(i + 1, i) * (altitude - h(i))) / dh(i + 1, i));
     return (ratio / Mo) * Tm;
 }
 /**
@@ -275,9 +275,9 @@ <h1 class="page-title">atmosphere.js</h1>
  * let speed = getSpeedOfSound(86000);
  * console.log(speed);// 274.6 m/s
 **/
-function getSpeedOfSound(altitude = 0) {
-    let temperature = getKineticTemperature(altitude);
-    let radicand = SPECIFIC_HEAT_RATIO * R * temperature;
+function getSpeedOfSound(altitude: number = 0): number {
+    const temperature = getKineticTemperature(altitude);
+    const radicand = SPECIFIC_HEAT_RATIO * R * temperature;
     return sqrt(radicand);
 }
 /**
@@ -291,7 +291,7 @@ <h1 class="page-title">atmosphere.js</h1>
  * metersPerSecondToMach(speed);// 1
  * metersPerSecondToMach(speed, 20000);// 1.15
 **/
-function metersPerSecondToMach(speed, altitude) {
+function metersPerSecondToMach(speed: number, altitude: number): number {
     return speed / getSpeedOfSound(altitude);
 }
 </code></pre>
@@ -306,7 +306,7 @@ <h1 class="page-title">atmosphere.js</h1>
 <br class="clear">
 
 <footer>
-    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Thu Oct 26 2017 19:09:26 GMT-0500 (CDT) using the Minami theme.
+    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Sat Oct 28 2017 21:27:59 GMT-0500 (CDT) using the Minami theme.
 </footer>
 
 <script>prettyPrint();</script>

docs/geodetic.js.html

@@ -39,12 +39,14 @@ <h1 class="page-title">geodetic.js</h1>
 
     <section>
         <article>
-            <pre class="prettyprint source linenums"><code>/**
+            <pre class="prettyprint source linenums"><code>// @flow
+type point2 = [number, number];
+type point3 = [number, number, number];
+/**
  * @file Geodesic, cartographic, and geographic
  * @author Jason Wohlgemuth
  * @module geodetic
 **/
-'use strict';
 
 const flatten  = require('lodash/flatten');
 const curry    = require('lodash/curry');
@@ -62,13 +64,13 @@ <h1 class="page-title">geodetic.js</h1>
 const SECONDS_PER_DEGREE = MINUTES_PER_DEGREE * SECONDS_PER_MINUTE;
 const GEOSPATIAL_VALUE_LENGTH = 3;
 
-function frac(float) {
+function frac(float: number): any {
     float = abs(float);
     let digits = (float !== trunc(float)) ? String(float).split('.')[1].length : 0;
     return (float - trunc(float)).toFixed(digits);
 }
 function clone(obj) {return JSON.parse(JSON.stringify(obj));}
-function squared(n) {return n * n;}
+function squared(n: number): number {return n * n;}
 function getArguments() {return Array.prototype.slice.apply(arguments);}
 function padArrayWithZeroes(n, arr) {return arr.concat(times(n - arr.length, constant(0)));}
 function onlyAllowNumbers(arr) {return arr.every(isNumber) ? arr : [];}
@@ -146,8 +148,8 @@ <h1 class="page-title">geodetic.js</h1>
  * @param {number} theta Geographic latitude
  * @returns {number} Geocentric latitude
 **/
-function getGeocentricLatitude(theta) {
-    let coefficient = squared(1 - DATUM.FLATTENING);
+function getGeocentricLatitude(theta: number): number {
+    const coefficient = squared(1 - DATUM.FLATTENING);
     return coefficient * tan(rad(theta));
 }
 /**
@@ -171,12 +173,12 @@ <h1 class="page-title">geodetic.js</h1>
  * console.log(r);// 6371001
  *
 **/
-function getRadius(theta) {
+function getRadius(theta: number): number {
     let radius;
     if (isNil(theta)) {
         radius = DATUM.EARTH_MEAN_RADIUS;
     } else {
-        let SIN_THETA = sin(getGeocentricLatitude(theta));
+        const SIN_THETA = sin(getGeocentricLatitude(theta));
         radius = DATUM.SEMI_MAJOR_AXIS * (1 - (DATUM.FLATTENING * squared(SIN_THETA)));
     }
     return radius;
@@ -193,15 +195,15 @@ <h1 class="page-title">geodetic.js</h1>
  * let distance = getHaversineDistance(a, b);
  * console.log(distance);// about 2098 km
 **/
-function getHaversineDistance(pointA, pointB) {
-    let a = pointA.map(rad);
-    let b = pointB.map(rad);
-    let Δ = [
+function getHaversineDistance(pointA: point2, pointB: point2): number {
+    const a = pointA.map(rad);
+    const b = pointB.map(rad);
+    const Δ = [
         b[0] - a[0], // latitude
         b[1] - a[1] // longitude
     ];
     const R = DATUM.EARTH_AUTHALIC_RADIUS;
-    let inner = hav(Δ[0]) + (cos(a[0]) * cos(b[0]) * hav(Δ[1]));
+    const inner = hav(Δ[0]) + (cos(a[0]) * cos(b[0]) * hav(Δ[1]));
     return 2 * R * asin(sqrt(inner));
 }
 /**
@@ -211,20 +213,20 @@ <h1 class="page-title">geodetic.js</h1>
  * @property {number[]} point [latitude, longitude, height] (in degrees)
  * @returns {number[]} [x, y, z]
 **/
-function geodeticToCartesian(point) {
-    let [latitude, longitude, height] = point;
-    let h = height ? height : 0;
-    let lat = rad(latitude);
-    let lon = rad(longitude);
+function geodeticToCartesian(point: point3): point3 {
+    const [latitude, longitude, height] = point;
+    const h = height ? height : 0;
+    const lat = rad(latitude);
+    const lon = rad(longitude);
     const COS_LON = cos(lon);
     const COS_LAT = cos(lat);
     const SIN_LON = sin(lon);
     const SIN_LAT = sin(lat);
     const SIN_LAT_SQUARED = SIN_LAT * SIN_LAT;
     const N = DATUM.SEMI_MAJOR_AXIS / sqrt(1 - DATUM.FIRST_ECCENTRICITY_SQUARED * SIN_LAT_SQUARED);
-    let x = (N + h) * COS_LAT * COS_LON;
-    let y = (N + h) * COS_LAT * SIN_LON;
-    let z = ((1 - DATUM.FIRST_ECCENTRICITY_SQUARED) * N + h) * SIN_LAT;
+    const x = (N + h) * COS_LAT * COS_LON;
+    const y = (N + h) * COS_LAT * SIN_LON;
+    const z = ((1 - DATUM.FIRST_ECCENTRICITY_SQUARED) * N + h) * SIN_LAT;
     return [x, y, z];
 }
 /**
@@ -235,8 +237,8 @@ <h1 class="page-title">geodetic.js</h1>
  * @returns {number[]} [latitude, longitude, height] (in degrees)
  * @see [Cartesian to Geodetic Coordinates without Iterations]{@link http://dx.doi.org/10.1061/(ASCE)0733-9453(2000)126:1(1)}
 **/
-function cartesianToGeodetic(point) {
-    let [x, y, z] = point;
+function cartesianToGeodetic(point: point3): point3 {
+    const [x, y, z] = point;
     const a = DATUM.SEMI_MAJOR_AXIS;
     const b = DATUM.SEMI_MINOR_AXIS;
     const E = DATUM.LINEAR_ECCENTRICITY;
@@ -255,9 +257,9 @@ <h1 class="page-title">geodetic.js</h1>
     const REDUCED_LATITUDE = atan(TAN_REDUCED_LATITUDE);
     const COS_REDUCED_LATITUDE = cos(REDUCED_LATITUDE);
     const SIN_REDUCED_LATITUDE = sin(REDUCED_LATITUDE);
-    let latitude = atan((a / b) * TAN_REDUCED_LATITUDE);
-    let longitude = atan2(y, x);
-    let height = sqrt(
+    const latitude = atan((a / b) * TAN_REDUCED_LATITUDE);
+    const longitude = atan2(y, x);
+    const height = sqrt(
         squared(z - b * SIN_REDUCED_LATITUDE) + squared(Q - a * COS_REDUCED_LATITUDE)
     );
     return [deg(latitude), deg(longitude), Number(height.toFixed(1))];
@@ -278,13 +280,13 @@ <h1 class="page-title">geodetic.js</h1>
  * let dms = toDegreesMinutesSeconds(val);
  * console.log(dms);// [32, 49, 49.0800]
 **/
-function toDegreesMinutesSeconds(value) {
+function toDegreesMinutesSeconds(value: point3): ?number[] {
     if (value.length !== GEOSPATIAL_VALUE_LENGTH) {
         return null;
     }
-    let data = value;
-    let dimension = data.length - data.slice(0).reverse().findIndex(function(val) {return abs(val) > 0;});
-    let degrees = trunc(value[0]);
+    const data = value;
+    const dimension = data.length - data.slice(0).reverse().findIndex(function(val) {return abs(val) > 0;});
+    const degrees = trunc(value[0]);
     let minutes = 0;
     let seconds = 0;
     /* istanbul ignore else */
@@ -320,7 +322,7 @@ <h1 class="page-title">geodetic.js</h1>
  * let ddm = toDegreesDecimalMinutes(val);
  * console.log(ddm);// [32, 49.818]
 **/
-function toDegreesDecimalMinutes(value) {
+function toDegreesDecimalMinutes(value: point3): ?number[] {
     if (value.length !== GEOSPATIAL_VALUE_LENGTH) {
         return null;
     }
@@ -352,9 +354,9 @@ <h1 class="page-title">geodetic.js</h1>
  * let dd = toDecimalDegrees(val);
  * console.log(dd);// 32.8303
 **/
-function toDecimalDegrees(value) {
+function toDecimalDegrees(value: number[]): ?number {
     let data = value;
-    let sign = Math.sign(data[0]);
+    const sign = Math.sign(data[0]);
     data = data.map(Number).map(abs);
     data = sign * (data[0] + (data[1] / MINUTES_PER_DEGREE) + (data[2] / SECONDS_PER_DEGREE));
     return !isNaN(data) ? data : null;
@@ -371,7 +373,7 @@ <h1 class="page-title">geodetic.js</h1>
 <br class="clear">
 
 <footer>
-    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Thu Oct 26 2017 19:09:26 GMT-0500 (CDT) using the Minami theme.
+    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Sat Oct 28 2017 21:27:59 GMT-0500 (CDT) using the Minami theme.
 </footer>
 
 <script>prettyPrint();</script>

docs/index.html

@@ -110,7 +110,7 @@ <h2>License</h2><p><a href="https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgi
 <br class="clear">
 
 <footer>
-    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Thu Oct 26 2017 19:09:26 GMT-0500 (CDT) using the Minami theme.
+    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Sat Oct 28 2017 21:27:59 GMT-0500 (CDT) using the Minami theme.
 </footer>
 
 <script>prettyPrint();</script>

docs/math.js.html

@@ -39,12 +39,12 @@ <h1 class="page-title">math.js</h1>
 
     <section>
         <article>
-            <pre class="prettyprint source linenums"><code>/**
+            <pre class="prettyprint source linenums"><code>// @flow
+/**
  * @file Collection of common (and less common) mathematical utility functions
  * @author Jason Wohlgemuth
  * @module math
 **/
-'use strict';
 
 const {acos, cos, PI} = Math;
 
@@ -59,19 +59,19 @@ <h1 class="page-title">math.js</h1>
     ahav
 };
 
-function delta(fn) {
+function delta(fn: (number) => number): (number, number) => number {
     return (a, b) => (fn(a) - fn(b));
 }
-function deg(val) {
+function deg(val: number): number {
     return val * DEGREES_PER_RADIAN;
 }
-function rad(val) {
+function rad(val: number): number {
     return val * RADIANS_PER_DEGREE;
 }
-function hav(theta) {
+function hav(theta: number): number {
     return 0.5 * (1 - cos(theta));
 }
-function ahav(x) {
+function ahav(x: number): number {
     return acos(1 - (2 * x));
 }
 </code></pre>
@@ -86,7 +86,7 @@ <h1 class="page-title">math.js</h1>
 <br class="clear">
 
 <footer>
-    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Thu Oct 26 2017 19:09:26 GMT-0500 (CDT) using the Minami theme.
+    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Sat Oct 28 2017 21:27:59 GMT-0500 (CDT) using the Minami theme.
 </footer>
 
 <script>prettyPrint();</script>

docs/module-atmosphere-Atmospheric%20Strata.html

@@ -89,7 +89,7 @@ <h2>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="atmosphere.js.html">atmosphere.js</a>, <a href="atmosphere.js.html#line32">line 32</a>
+        <a href="atmosphere.js.html">atmosphere.js</a>, <a href="atmosphere.js.html#line9">line 9</a>
     </li></ul></dd>
 
 
@@ -134,7 +134,7 @@ <h2>
 <br class="clear">
 
 <footer>
-    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Thu Oct 26 2017 19:09:26 GMT-0500 (CDT) using the Minami theme.
+    Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.3</a> on Sat Oct 28 2017 21:27:59 GMT-0500 (CDT) using the Minami theme.
 </footer>
 
 <script>prettyPrint();</script>