Docs: Replaced nullable types with explicit type|null for better tool…

…ing compatibility, also fixes #766 and fixes 767

cli/targets/static.js

@@ -514,7 +514,7 @@ function buildType(ref, type) {
         pushComment([
             "Verifies " + aOrAn(type.name) + " message.",
             "@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " Plain object to verify",
-            "@returns {?string} `null` if valid, otherwise the reason why it is not"
+            "@returns {string|null} `null` if valid, otherwise the reason why it is not"
         ]);
         buildFunction(type, "verify", protobuf.verifier(type));
     }
@@ -597,7 +597,7 @@ function buildService(ref, service) {
             // This is a more specialized version of protobuf.rpc.ServiceCallback
             "@typedef " + cbName,
             "@type {function}",
-            "@param {?Error} error Error, if any",
+            "@param {Error|null} error Error, if any",
             "@param {" + method.resolvedResponseType.fullName.substring(1) + "} [response] " + method.resolvedResponseType.name
         ]);
         push("");

index.d.ts

@@ -24,7 +24,7 @@ export namespace common {
      * @param file Proto file name
      * @returns Root definition or `null` if not defined
      */
-    function get(file: string): INamespace;
+    function get(file: string): (INamespace|null);
 
     /** Properties of a google.protobuf.Any message. */
     interface IAny {
@@ -186,12 +186,12 @@ export class Enum extends ReflectionObject {
      * Adds a value to this enum.
      * @param name Value name
      * @param id Value id
-     * @param comment Comment, if any
+     * @param [comment] Comment, if any
      * @returns `this`
      * @throws {TypeError} If arguments are invalid
      * @throws {Error} If there is already a value with this name or id
      */
-    public add(name: string, id: number, comment: string): Enum;
+    public add(name: string, id: number, comment?: string): Enum;
 
     /**
      * Removes a value from this enum
@@ -298,10 +298,10 @@ export class FieldBase extends ReflectionObject {
     public map: boolean;
 
     /** Message this field belongs to. */
-    public message: Type;
+    public message: (Type|null);
 
     /** OneOf this field belongs to, if any, */
-    public partOf: OneOf;
+    public partOf: (OneOf|null);
 
     /** The field type's default value. */
     public typeDefault: any;
@@ -316,13 +316,13 @@ export class FieldBase extends ReflectionObject {
     public bytes: boolean;
 
     /** Resolved type if not a basic type. */
-    public resolvedType: (Type|Enum);
+    public resolvedType: (Type|Enum|null);
 
     /** Sister-field within the extended type if a declaring extension field. */
-    public extensionField: Field;
+    public extensionField: (Field|null);
 
     /** Sister-field within the declaring namespace if an extended field. */
-    public declaringField: Field;
+    public declaringField: (Field|null);
 
     /**
      * Converts this field to a field descriptor.
@@ -373,7 +373,7 @@ type FieldDecorator = (prototype: object, fieldName: string) => void;
  * @param error Error, if any, otherwise `null`
  * @param [root] Root, if there hasn't been an error
  */
-type LoadCallback = (error: Error, root?: Root) => void;
+type LoadCallback = (error: (Error|null), root?: Root) => void;
 
 /**
  * Loads one or multiple .proto or preprocessed .json files into a common root namespace and calls the callback.
@@ -434,7 +434,7 @@ export class MapField extends FieldBase {
     public keyType: string;
 
     /** Resolved key type if not a basic type. */
-    public resolvedKeyType: ReflectionObject;
+    public resolvedKeyType: (ReflectionObject|null);
 
     /**
      * Constructs a map field from a map field descriptor.
@@ -532,7 +532,7 @@ export class Message<T extends object> {
      * @param message Plain object to verify
      * @returns `null` if valid, otherwise the reason why it is not
      */
-    public static verify(message: { [k: string]: any }): string;
+    public static verify(message: { [k: string]: any }): (string|null);
 
     /**
      * Creates a new message of this type from a plain object. Also converts values to their respective internal types.
@@ -587,10 +587,10 @@ export class Method extends ReflectionObject {
     public responseStream?: boolean;
 
     /** Resolved request type. */
-    public resolvedRequestType: Type;
+    public resolvedRequestType: (Type|null);
 
     /** Resolved response type. */
-    public resolvedResponseType: Type;
+    public resolvedResponseType: (Type|null);
 
     /**
      * Constructs a method from a method descriptor.
@@ -684,7 +684,7 @@ export abstract class NamespaceBase extends ReflectionObject {
      * @param name Nested object name
      * @returns The reflection object or `null` if it doesn't exist
      */
-    public get(name: string): ReflectionObject;
+    public get(name: string): (ReflectionObject|null);
 
     /**
      * Gets the values of the nested {@link Enum|enum} of the specified name.
@@ -734,15 +734,15 @@ export abstract class NamespaceBase extends ReflectionObject {
      * @param [parentAlreadyChecked=false] If known, whether the parent has already been checked
      * @returns Looked up object or `null` if none could be found
      */
-    public lookup(path: (string|string[]), filterTypes: (any|any[]), parentAlreadyChecked?: boolean): ReflectionObject;
+    public lookup(path: (string|string[]), filterTypes: (any|any[]), parentAlreadyChecked?: boolean): (ReflectionObject|null);
 
     /**
      * Looks up the reflection object at the specified path, relative to this namespace.
      * @param path Path to look up
      * @param [parentAlreadyChecked=false] Whether the parent has already been checked
      * @returns Looked up object or `null` if none could be found
      */
-    public lookup(path: (string|string[]), parentAlreadyChecked?: boolean): ReflectionObject;
+    public lookup(path: (string|string[]), parentAlreadyChecked?: boolean): (ReflectionObject|null);
 
     /**
      * Looks up the {@link Type|type} at the specified path, relative to this namespace.
@@ -807,16 +807,16 @@ export abstract class ReflectionObject {
     public name: string;
 
     /** Parent namespace. */
-    public parent: Namespace;
+    public parent: (Namespace|null);
 
     /** Whether already resolved or not. */
     public resolved: boolean;
 
     /** Comment text, if any. */
-    public comment: string;
+    public comment: (string|null);
 
     /** Defining file name. */
-    public filename: string;
+    public filename: (string|null);
 
     /** Reference to the root namespace. */
     public readonly root: Root;
@@ -1173,7 +1173,7 @@ export class Root extends NamespaceBase {
      * @param target The file name being imported
      * @returns Resolved path to `target` or `null` to skip the file
      */
-    public resolvePath(origin: string, target: string): string;
+    public resolvePath(origin: string, target: string): (string|null);
 
     /**
      * Loads one or multiple .proto or preprocessed .json files into this root namespace and calls the callback.
@@ -1218,7 +1218,7 @@ export namespace rpc {
      * @param error Error, if any
      * @param [response] Response message
      */
-    type ServiceMethodCallback<TRes extends Message<TRes>> = (error: Error, response?: TRes) => void;
+    type ServiceMethodCallback<TRes extends Message<TRes>> = (error: (Error|null), response?: TRes) => void;
 
     /**
      * A service method part of a {@link rpc.Service} as created by {@link Service.create}.
@@ -1240,7 +1240,7 @@ export namespace rpc {
         constructor(rpcImpl: RPCImpl, requestDelimited?: boolean, responseDelimited?: boolean);
 
         /** RPC implementation. Becomes `null` once the service is ended. */
-        public rpcImpl: RPCImpl;
+        public rpcImpl: (RPCImpl|null);
 
         /** Whether requests are length-delimited. */
         public requestDelimited: boolean;
@@ -1280,7 +1280,7 @@ type RPCImpl = (method: (Method|rpc.ServiceMethod<Message<{}>, Message<{}>>), re
  * @param error Error, if any, otherwise `null`
  * @param [response] Response data or `null` to signal end of stream, if there hasn't been an error
  */
-type RPCImplCallback = (error: Error, response?: Uint8Array) => void;
+type RPCImplCallback = (error: (Error|null), response?: (Uint8Array|null)) => void;
 
 /** Reflected service. */
 export class Service extends NamespaceBase {
@@ -1335,13 +1335,13 @@ export interface IService extends INamespace {
  * Gets the next token and advances.
  * @returns Next token or `null` on eof
  */
-type TokenizerHandleNext = () => string;
+type TokenizerHandleNext = () => (string|null);
 
 /**
  * Peeks for the next token.
  * @returns Next token or `null` on eof
  */
-type TokenizerHandlePeek = () => string;
+type TokenizerHandlePeek = () => (string|null);
 
 /**
  * Pushes a token back to the stack.
@@ -1363,7 +1363,7 @@ type TokenizerHandleSkip = (expected: string, optional?: boolean) => boolean;
  * @param [line] Line number
  * @returns Comment text or `null` if none
  */
-type TokenizerHandleCmnt = (line?: number) => string;
+type TokenizerHandleCmnt = (line?: number) => (string|null);
 
 /** Handle object returned from {@link tokenize}. */
 export interface ITokenizerHandle {
@@ -1547,7 +1547,7 @@ export class Type extends NamespaceBase {
      * @param message Plain object to verify
      * @returns `null` if valid, otherwise the reason why it is not
      */
-    public verify(message: { [k: string]: any }): string;
+    public verify(message: { [k: string]: any }): (null|string);
 
     /**
      * Creates a new message of this type from a plain object. Also converts values to their respective internal types.
@@ -2381,7 +2381,7 @@ export class Writer {
     public tail: object;
 
     /** Linked forked states. */
-    public states: object;
+    public states: (object|null);
 
     /**
      * Creates a new writer.

src/common.js

@@ -42,7 +42,7 @@ function common(name, json) {
  * @name common.get
  * @function
  * @param {string} file Proto file name
- * @returns {?INamespace} Root definition or `null` if not defined
+ * @returns {INamespace|null} Root definition or `null` if not defined
  */
 common.get = function get(file) {
     return common[file] || null;

src/enum.js

@@ -83,7 +83,7 @@ Enum.prototype.toJSON = function toJSON() {
  * Adds a value to this enum.
  * @param {string} name Value name
  * @param {number} id Value id
- * @param {?string} comment Comment, if any
+ * @param {string} [comment] Comment, if any
  * @returns {Enum} `this`
  * @throws {TypeError} If arguments are invalid
  * @throws {Error} If there is already a value with this name or id

src/field.js

@@ -125,13 +125,13 @@ function Field(name, id, type, rule, extend, options) {
 
     /**
      * Message this field belongs to.
-     * @type {?Type}
+     * @type {Type|null}
      */
     this.message = null;
 
     /**
      * OneOf this field belongs to, if any,
-     * @type {?OneOf}
+     * @type {OneOf|null}
      */
     this.partOf = null;
 
@@ -161,25 +161,25 @@ function Field(name, id, type, rule, extend, options) {
 
     /**
      * Resolved type if not a basic type.
-     * @type {?(Type|Enum)}
+     * @type {Type|Enum|null}
      */
     this.resolvedType = null;
 
     /**
      * Sister-field within the extended type if a declaring extension field.
-     * @type {?Field}
+     * @type {Field|null}
      */
     this.extensionField = null;
 
     /**
      * Sister-field within the declaring namespace if an extended field.
-     * @type {?Field}
+     * @type {Field|null}
      */
     this.declaringField = null;
 
     /**
      * Internally remembers whether this field is packed.
-     * @type {?boolean}
+     * @type {boolean|null}
      * @private
      */
     this._packed = null;

src/index-light.js

@@ -7,7 +7,7 @@ protobuf.build = "light";
  * A node-style callback as used by {@link load} and {@link Root#load}.
  * @typedef LoadCallback
  * @type {function}
- * @param {?Error} error Error, if any, otherwise `null`
+ * @param {Error|null} error Error, if any, otherwise `null`
  * @param {Root} [root] Root, if there hasn't been an error
  * @returns {undefined}
  */

src/mapfield.js

@@ -34,7 +34,7 @@ function MapField(name, id, keyType, type, options) {
 
     /**
      * Resolved key type if not a basic type.
-     * @type {?ReflectionObject}
+     * @type {ReflectionObject|null}
      */
     this.resolvedKeyType = null;
 

src/message.js

@@ -99,7 +99,7 @@ Message.decodeDelimited = function decodeDelimited(reader) {
  * @name Message.verify
  * @function
  * @param {Object.<string,*>} message Plain object to verify
- * @returns {?string} `null` if valid, otherwise the reason why it is not
+ * @returns {string|null} `null` if valid, otherwise the reason why it is not
  */
 Message.verify = function verify(message) {
     return this.$type.verify(message);

src/method.js

@@ -77,13 +77,13 @@ function Method(name, type, requestType, responseType, requestStream, responseSt
 
     /**
      * Resolved request type.
-     * @type {?Type}
+     * @type {Type|null}
      */
     this.resolvedRequestType = null;
 
     /**
      * Resolved response type.
-     * @type {?Type}
+     * @type {Type|null}
      */
     this.resolvedResponseType = null;
 }

src/namespace.js

@@ -74,7 +74,7 @@ function Namespace(name, options) {
 
     /**
      * Cached nested objects as an array.
-     * @type {?ReflectionObject[]}
+     * @type {ReflectionObject[]|null}
      * @private
      */
     this._nestedArray = null;
@@ -158,7 +158,7 @@ Namespace.prototype.addJSON = function addJSON(nestedJson) {
 /**
  * Gets the nested object of the specified name.
  * @param {string} name Nested object name
- * @returns {?ReflectionObject} The reflection object or `null` if it doesn't exist
+ * @returns {ReflectionObject|null} The reflection object or `null` if it doesn't exist
  */
 Namespace.prototype.get = function get(name) {
     return this.nested && this.nested[name]
@@ -285,7 +285,7 @@ Namespace.prototype.resolveAll = function resolveAll() {
  * @param {string|string[]} path Path to look up
  * @param {*|Array.<*>} filterTypes Filter types, any combination of the constructors of `protobuf.Type`, `protobuf.Enum`, `protobuf.Service` etc.
  * @param {boolean} [parentAlreadyChecked=false] If known, whether the parent has already been checked
- * @returns {?ReflectionObject} Looked up object or `null` if none could be found
+ * @returns {ReflectionObject|null} Looked up object or `null` if none could be found
  */
 Namespace.prototype.lookup = function lookup(path, filterTypes, parentAlreadyChecked) {
 
@@ -334,7 +334,7 @@ Namespace.prototype.lookup = function lookup(path, filterTypes, parentAlreadyChe
  * @function
  * @param {string|string[]} path Path to look up
  * @param {boolean} [parentAlreadyChecked=false] Whether the parent has already been checked
- * @returns {?ReflectionObject} Looked up object or `null` if none could be found
+ * @returns {ReflectionObject|null} Looked up object or `null` if none could be found
  * @variation 2
  */
 // lookup(path: string, [parentAlreadyChecked: boolean])