CLI: With null/undefined eliminated by constructors and .create, docu…

…ment message fields as non-optional where applicable (ideally used with TS & strictNullChecks), see #743
protobufjs · Apr 4, 2017 · bed5142 · bed5142
1 parent a66f764
commit bed5142
Show file tree

Hide file tree

Showing 10 changed files with 437 additions and 432 deletions.
diff --git a/cli/targets/static.js b/cli/targets/static.js
@@ -333,9 +333,11 @@ function toJsType(field) {
                 type = "*"; // should not happen
             break;
     }
-    return field.repeated ? "Array.<" + type + ">"
-         : field.map ? "Object.<string," + type + ">"
-         : type;
+    if (field.map)
+        return "Object.<string," + type + ">";
+    if (field.repeated)
+        return "Array.<" + type + ">";
+    return type;
 }
 
 function buildType(ref, type) {
@@ -374,9 +376,12 @@ function buildType(ref, type) {
         var prop = util.safeProp(field.name);
         if (config.comments) {
             push("");
+            var jsType = toJsType(field);
+            if (field.optional && !field.map && !field.repeated && field.resolvedType instanceof Type)
+                jsType = "(" + jsType + "|null)";
             pushComment([
                 field.comment || type.name + " " + field.name + ".",
-                "@type {" + toJsType(field) + (field.optional ? "|undefined" : "") + "}"
+                "@type {" + jsType + "}"
             ]);
         } else if (firstField) {
             push("");

diff --git a/tests/data/comments.js b/tests/data/comments.js
@@ -39,19 +39,19 @@ $root.Test1 = (function() {
 
     /**
      * Field with a comment.
-     * @type {string|undefined}
+     * @type {string}
      */
     Test1.prototype.field1 = "";
 
     /**
      * Test1 field2.
-     * @type {number|undefined}
+     * @type {number}
      */
     Test1.prototype.field2 = 0;
 
     /**
      * Field with a comment and a <a href="http://example.com/foo/">link</a>
-     * @type {boolean|undefined}
+     * @type {boolean}
      */
     Test1.prototype.field3 = false;
 

diff --git a/tests/data/convert.js b/tests/data/convert.js
@@ -46,55 +46,55 @@ $root.Message = (function() {
 
     /**
      * Message stringVal.
-     * @type {string|undefined}
+     * @type {string}
      */
     Message.prototype.stringVal = "";
 
     /**
      * Message stringRepeated.
-     * @type {Array.<string>|undefined}
+     * @type {Array.<string>}
      */
     Message.prototype.stringRepeated = $util.emptyArray;
 
     /**
      * Message uint64Val.
-     * @type {number|Long|undefined}
+     * @type {number|Long}
      */
     Message.prototype.uint64Val = $util.Long ? $util.Long.fromBits(0,0,true) : 0;
 
     /**
      * Message uint64Repeated.
-     * @type {Array.<number|Long>|undefined}
+     * @type {Array.<number|Long>}
      */
     Message.prototype.uint64Repeated = $util.emptyArray;
 
     /**
      * Message bytesVal.
-     * @type {Uint8Array|undefined}
+     * @type {Uint8Array}
      */
     Message.prototype.bytesVal = $util.newBuffer([]);
 
     /**
      * Message bytesRepeated.
-     * @type {Array.<Uint8Array>|undefined}
+     * @type {Array.<Uint8Array>}
      */
     Message.prototype.bytesRepeated = $util.emptyArray;
 
     /**
      * Message enumVal.
-     * @type {Message.SomeEnum|undefined}
+     * @type {Message.SomeEnum}
      */
     Message.prototype.enumVal = 1;
 
     /**
      * Message enumRepeated.
-     * @type {Array.<Message.SomeEnum>|undefined}
+     * @type {Array.<Message.SomeEnum>}
      */
     Message.prototype.enumRepeated = $util.emptyArray;
 
     /**
      * Message int64Map.
-     * @type {Object.<string,number|Long>|undefined}
+     * @type {Object.<string,number|Long>}
      */
     Message.prototype.int64Map = $util.emptyObject;
 

diff --git a/tests/data/mapbox/vector_tile.js b/tests/data/mapbox/vector_tile.js
@@ -43,7 +43,7 @@ $root.vector_tile = (function() {
 
         /**
          * Tile layers.
-         * @type {Array.<vector_tile.Tile.Layer$Properties>|undefined}
+         * @type {Array.<vector_tile.Tile.Layer$Properties>}
          */
         Tile.prototype.layers = $util.emptyArray;
 
@@ -259,43 +259,43 @@ $root.vector_tile = (function() {
 
             /**
              * Value stringValue.
-             * @type {string|undefined}
+             * @type {string}
              */
             Value.prototype.stringValue = "";
 
             /**
              * Value floatValue.
-             * @type {number|undefined}
+             * @type {number}
              */
             Value.prototype.floatValue = 0;
 
             /**
              * Value doubleValue.
-             * @type {number|undefined}
+             * @type {number}
              */
             Value.prototype.doubleValue = 0;
 
             /**
              * Value intValue.
-             * @type {number|Long|undefined}
+             * @type {number|Long}
              */
             Value.prototype.intValue = $util.Long ? $util.Long.fromBits(0,0,false) : 0;
 
             /**
              * Value uintValue.
-             * @type {number|Long|undefined}
+             * @type {number|Long}
              */
             Value.prototype.uintValue = $util.Long ? $util.Long.fromBits(0,0,true) : 0;
 
             /**
              * Value sintValue.
-             * @type {number|Long|undefined}
+             * @type {number|Long}
              */
             Value.prototype.sintValue = $util.Long ? $util.Long.fromBits(0,0,false) : 0;
 
             /**
              * Value boolValue.
-             * @type {boolean|undefined}
+             * @type {boolean}
              */
             Value.prototype.boolValue = false;
 
@@ -595,25 +595,25 @@ $root.vector_tile = (function() {
 
             /**
              * Feature id.
-             * @type {number|Long|undefined}
+             * @type {number|Long}
              */
             Feature.prototype.id = $util.Long ? $util.Long.fromBits(0,0,true) : 0;
 
             /**
              * Feature tags.
-             * @type {Array.<number>|undefined}
+             * @type {Array.<number>}
              */
             Feature.prototype.tags = $util.emptyArray;
 
             /**
              * Feature type.
-             * @type {vector_tile.Tile.GeomType|undefined}
+             * @type {vector_tile.Tile.GeomType}
              */
             Feature.prototype.type = 0;
 
             /**
              * Feature geometry.
-             * @type {Array.<number>|undefined}
+             * @type {Array.<number>}
              */
             Feature.prototype.geometry = $util.emptyArray;
 
@@ -932,25 +932,25 @@ $root.vector_tile = (function() {
 
             /**
              * Layer features.
-             * @type {Array.<vector_tile.Tile.Feature$Properties>|undefined}
+             * @type {Array.<vector_tile.Tile.Feature$Properties>}
              */
             Layer.prototype.features = $util.emptyArray;
 
             /**
              * Layer keys.
-             * @type {Array.<string>|undefined}
+             * @type {Array.<string>}
              */
             Layer.prototype.keys = $util.emptyArray;
 
             /**
              * Layer values.
-             * @type {Array.<vector_tile.Tile.Value$Properties>|undefined}
+             * @type {Array.<vector_tile.Tile.Value$Properties>}
              */
             Layer.prototype.values = $util.emptyArray;
 
             /**
              * Layer extent.
-             * @type {number|undefined}
+             * @type {number}
              */
             Layer.prototype.extent = 4096;
 

diff --git a/tests/data/package.js b/tests/data/package.js
@@ -57,109 +57,109 @@ $root.Package = (function() {
 
     /**
      * Package name.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.name = "";
 
     /**
      * Package version.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.version = "";
 
     /**
      * Package versionScheme.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.versionScheme = "";
 
     /**
      * Package description.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.description = "";
 
     /**
      * Package author.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.author = "";
 
     /**
      * Package license.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.license = "";
 
     /**
      * Package repository.
-     * @type {Package.Repository$Properties|undefined}
+     * @type {(Package.Repository$Properties|null)}
      */
     Package.prototype.repository = null;
 
     /**
      * Package bugs.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.bugs = "";
 
     /**
      * Package homepage.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.homepage = "";
 
     /**
      * Package keywords.
-     * @type {Array.<string>|undefined}
+     * @type {Array.<string>}
      */
     Package.prototype.keywords = $util.emptyArray;
 
     /**
      * Package main.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.main = "";
 
     /**
      * Package bin.
-     * @type {Object.<string,string>|undefined}
+     * @type {Object.<string,string>}
      */
     Package.prototype.bin = $util.emptyObject;
 
     /**
      * Package scripts.
-     * @type {Object.<string,string>|undefined}
+     * @type {Object.<string,string>}
      */
     Package.prototype.scripts = $util.emptyObject;
 
     /**
      * Package dependencies.
-     * @type {Object.<string,string>|undefined}
+     * @type {Object.<string,string>}
      */
     Package.prototype.dependencies = $util.emptyObject;
 
     /**
      * Package optionalDependencies.
-     * @type {Object.<string,string>|undefined}
+     * @type {Object.<string,string>}
      */
     Package.prototype.optionalDependencies = $util.emptyObject;
 
     /**
      * Package devDependencies.
-     * @type {Object.<string,string>|undefined}
+     * @type {Object.<string,string>}
      */
     Package.prototype.devDependencies = $util.emptyObject;
 
     /**
      * Package types.
-     * @type {string|undefined}
+     * @type {string}
      */
     Package.prototype.types = "";
 
     /**
      * Package cliDependencies.
-     * @type {Array.<string>|undefined}
+     * @type {Array.<string>}
      */
     Package.prototype.cliDependencies = $util.emptyArray;
 
@@ -688,13 +688,13 @@ $root.Package = (function() {
 
         /**
          * Repository type.
-         * @type {string|undefined}
+         * @type {string}
          */
         Repository.prototype.type = "";
 
         /**
          * Repository url.
-         * @type {string|undefined}
+         * @type {string}
          */
         Repository.prototype.url = "";
 

diff --git a/tests/data/rpc-es6.js b/tests/data/rpc-es6.js
@@ -89,7 +89,7 @@ export const MyRequest = $root.MyRequest = (() => {
 
     /**
      * MyRequest path.
-     * @type {string|undefined}
+     * @type {string}
      */
     MyRequest.prototype.path = "";
 
@@ -263,7 +263,7 @@ export const MyResponse = $root.MyResponse = (() => {
 
     /**
      * MyResponse status.
-     * @type {number|undefined}
+     * @type {number}
      */
     MyResponse.prototype.status = 0;