Better documentation of properties that may be undefined

bmaupin · Sep 15, 2017 · 6c97f3e · 6c97f3e
1 parent 3b52430
commit 6c97f3e
Show file tree

Hide file tree

Showing 11 changed files with 23,167 additions and 23,136 deletions.
diff --git a/docs/ast/source/Civ5Save.js.json b/docs/ast/source/Civ5Save.js.json
diff --git a/docs/ast/source/ExtendableError.js.json b/docs/ast/source/ExtendableError.js.json
diff --git a/docs/class/src/Civ5Save.js~Civ5Save.html b/docs/class/src/Civ5Save.js~Civ5Save.html
diff --git a/docs/class/src/Civ5Save.js~InvalidSignatureError.html b/docs/class/src/Civ5Save.js~InvalidSignatureError.html
@@ -37,13 +37,13 @@
 </nav>
 
 <div class="content" data-ice="content"><div class="header-notice">
-  <div data-ice="importPath" class="import-path"><pre class="prettyprint"><code data-ice="importPathCode">import {InvalidSignatureError} from &apos;<span><a href="file/src/Civ5Save.js.html#lineNumber1021">civ5save/src/Civ5Save.js</a></span>&apos;</code></pre></div>
+  <div data-ice="importPath" class="import-path"><pre class="prettyprint"><code data-ice="importPathCode">import {InvalidSignatureError} from &apos;<span><a href="file/src/Civ5Save.js.html#lineNumber1032">civ5save/src/Civ5Save.js</a></span>&apos;</code></pre></div>
   <span data-ice="access">public</span>
   <span data-ice="kind">class</span>
 
 
 
-  <span data-ice="source">| <span><a href="file/src/Civ5Save.js.html#lineNumber1021">source</a></span></span>
+  <span data-ice="source">| <span><a href="file/src/Civ5Save.js.html#lineNumber1032">source</a></span></span>
 </div>
 
 <div class="self-detail detail">

diff --git a/docs/class/src/Civ5Save.js~ParseError.html b/docs/class/src/Civ5Save.js~ParseError.html
@@ -37,13 +37,13 @@
 </nav>
 
 <div class="content" data-ice="content"><div class="header-notice">
-  <div data-ice="importPath" class="import-path"><pre class="prettyprint"><code data-ice="importPathCode">import {ParseError} from &apos;<span><a href="file/src/Civ5Save.js.html#lineNumber1026">civ5save/src/Civ5Save.js</a></span>&apos;</code></pre></div>
+  <div data-ice="importPath" class="import-path"><pre class="prettyprint"><code data-ice="importPathCode">import {ParseError} from &apos;<span><a href="file/src/Civ5Save.js.html#lineNumber1037">civ5save/src/Civ5Save.js</a></span>&apos;</code></pre></div>
   <span data-ice="access">public</span>
   <span data-ice="kind">class</span>
 
 
 
-  <span data-ice="source">| <span><a href="file/src/Civ5Save.js.html#lineNumber1026">source</a></span></span>
+  <span data-ice="source">| <span><a href="file/src/Civ5Save.js.html#lineNumber1037">source</a></span></span>
 </div>
 
 <div class="self-detail detail">

diff --git a/docs/file/src/Civ5Save.js.html b/docs/file/src/Civ5Save.js.html
@@ -338,7 +338,11 @@
 
   /**
    * Game version.
-   * @type {string}
+   *
+   * Note that this will be `undefined` if [gameBuild](#instance-get-gameBuild) is less than 230620. `undefined` is used
+   * instead of `null` because older save files do not have a spot for this information (`null` might incorrectly imply
+   * the spot is there but empty).
+   * @type {string|undefined}
    */
   get gameVersion() {
     return this._getPropertyIfDefined(&apos;gameVersion&apos;);
@@ -354,7 +358,11 @@
 
   /**
    * Game mode: one of `Civ5Save.GAME_MODES.SINGLE`, `Civ5Save.GAME_MODES.MULTI`, or `Civ5Save.GAME_MODES.HOTSEAT`.
-   * @type {string}
+   *
+   * Note that this will be `undefined` if [gameBuild](#instance-get-gameBuild) is less than 230620. `undefined` is used
+   * instead of `null` because older save files do not have a spot for this information (`null` might incorrectly imply
+   * the spot is there but empty).
+   * @type {string|undefined}
    */
   get gameMode() {
     if (Number(this.gameBuild) &gt;= 230620) {
@@ -424,10 +432,13 @@
   }
 
   /**
-   * List of players with their civilization and status as properties. Civilization may be `undefined`. Status is one
-   *     of `Civ5Save.PLAYER_STATUSES.AI`, `Civ5Save.PLAYER_STATUSES.DEAD`, `Civ5Save.PLAYER_STATUSES.HUMAN`,
+   * List of players as objects with their civilization and status as properties.
+   *
+   * Civilization will be `undefined` if [gameBuild](#instance-get-gameBuild) is less than 310700.
+   *
+   * Status is one of `Civ5Save.PLAYER_STATUSES.AI`, `Civ5Save.PLAYER_STATUSES.DEAD`, `Civ5Save.PLAYER_STATUSES.HUMAN`,
    *     `Civ5Save.PLAYER_STATUSES.NONE`.
-   * @type {Array}
+   * @type {Array.&lt;{civilization: string|undefined, status: number}&gt;}
    */
   get players() {
     if (this._isNullOrUndefined(this._players)) {

diff --git a/docs/file/src/ExtendableError.js.html b/docs/file/src/ExtendableError.js.html
@@ -47,9 +47,9 @@
    */
   constructor(message) {
     super(message);
-  /**
-   * @ignore
-   */
+    /**
+     * @ignore
+     */
     this.name = this.constructor.name;
     if (typeof Error.captureStackTrace === &apos;function&apos;) {
       Error.captureStackTrace(this, this.constructor);

diff --git a/docs/index.json b/docs/index.json
diff --git a/docs/source.html b/docs/source.html
@@ -57,9 +57,9 @@
 <span><a href="class/src/Civ5Save.js~InvalidSignatureError.html">InvalidSignatureError</a></span>
 <span><a href="class/src/Civ5Save.js~ParseError.html">ParseError</a></span></td>
       <td class="coverage"><span data-ice="coverage">100 %</span><span data-ice="coverageCount" class="coverage-count">97/97</span></td>
-      <td style="display: none;" data-ice="size">27065 byte</td>
-      <td style="display: none;" data-ice="lines">1026</td>
-      <td style="display: none;" data-ice="updated">2017-09-06 16:52:50 (UTC)</td>
+      <td style="display: none;" data-ice="size">27781 byte</td>
+      <td style="display: none;" data-ice="lines">1037</td>
+      <td style="display: none;" data-ice="updated">2017-09-06 17:31:23 (UTC)</td>
     </tr>
 <tr data-ice="file">
       <td data-ice="filePath"><span><a href="file/src/Civ5SaveBoolProperty.js.html">src/Civ5SaveBoolProperty.js</a></span></td>
@@ -145,9 +145,9 @@
       <td data-ice="filePath"><span><a href="file/src/ExtendableError.js.html">src/ExtendableError.js</a></span></td>
       <td data-ice="identifier" class="identifiers">-</td>
       <td class="coverage"><span data-ice="coverage">100 %</span><span data-ice="coverageCount" class="coverage-count">4/4</span></td>
-      <td style="display: none;" data-ice="size">479 byte</td>
+      <td style="display: none;" data-ice="size">485 byte</td>
       <td style="display: none;" data-ice="lines">24</td>
-      <td style="display: none;" data-ice="updated">2017-09-06 16:37:31 (UTC)</td>
+      <td style="display: none;" data-ice="updated">2017-09-06 16:57:19 (UTC)</td>
     </tr>
 </tbody>
 </table>

diff --git a/src/Civ5Save.js b/src/Civ5Save.js
@@ -299,7 +299,11 @@ class Civ5Save {
 
   /**
    * Game version.
-   * @type {string}
+   *
+   * Note that this will be `undefined` if [gameBuild](#instance-get-gameBuild) is less than 230620. `undefined` is used
+   * instead of `null` because older save files do not have a spot for this information (`null` might incorrectly imply
+   * the spot is there but empty).
+   * @type {string|undefined}
    */
   get gameVersion() {
     return this._getPropertyIfDefined('gameVersion');
@@ -315,7 +319,11 @@ class Civ5Save {
 
   /**
    * Game mode: one of `Civ5Save.GAME_MODES.SINGLE`, `Civ5Save.GAME_MODES.MULTI`, or `Civ5Save.GAME_MODES.HOTSEAT`.
-   * @type {string}
+   *
+   * Note that this will be `undefined` if [gameBuild](#instance-get-gameBuild) is less than 230620. `undefined` is used
+   * instead of `null` because older save files do not have a spot for this information (`null` might incorrectly imply
+   * the spot is there but empty).
+   * @type {string|undefined}
    */
   get gameMode() {
     if (Number(this.gameBuild) >= 230620) {
@@ -385,10 +393,13 @@ class Civ5Save {
   }
 
   /**
-   * List of players with their civilization and status as properties. Civilization may be `undefined`. Status is one
-   *     of `Civ5Save.PLAYER_STATUSES.AI`, `Civ5Save.PLAYER_STATUSES.DEAD`, `Civ5Save.PLAYER_STATUSES.HUMAN`,
+   * List of players as objects with their civilization and status as properties.
+   *
+   * Civilization will be `undefined` if [gameBuild](#instance-get-gameBuild) is less than 310700.
+   *
+   * Status is one of `Civ5Save.PLAYER_STATUSES.AI`, `Civ5Save.PLAYER_STATUSES.DEAD`, `Civ5Save.PLAYER_STATUSES.HUMAN`,
    *     `Civ5Save.PLAYER_STATUSES.NONE`.
-   * @type {Array}
+   * @type {Array.<{civilization: string|undefined, status: number}>}
    */
   get players() {
     if (this._isNullOrUndefined(this._players)) {

diff --git a/src/ExtendableError.js b/src/ExtendableError.js
@@ -8,9 +8,9 @@ export default class ExtendableError extends Error {
    */
   constructor(message) {
     super(message);
-  /**
-   * @ignore
-   */
+    /**
+     * @ignore
+     */
     this.name = this.constructor.name;
     if (typeof Error.captureStackTrace === 'function') {
       Error.captureStackTrace(this, this.constructor);