Skip to content

Commit 23f4b99

Browse files
dcodeIOdcodeIO
committed
Docs: Replaced nullable types with explicit type|null for better tooling compatibility, also fixes #766 and fixes 767
1 parent a18e6db commit 23f4b99

19 files changed

Lines changed: 71 additions & 85 deletions

‎cli/targets/static.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -514,7 +514,7 @@ function buildType(ref, type) {
514514
pushComment([
515515
"Verifies " + aOrAn(type.name) + " message.",
516516
"@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " Plain object to verify",
517-
"@returns {?string} `null` if valid, otherwise the reason why it is not"
517+
"@returns {string|null} `null` if valid, otherwise the reason why it is not"
518518
]);
519519
buildFunction(type, "verify", protobuf.verifier(type));
520520
}
@@ -597,7 +597,7 @@ function buildService(ref, service) {
597597
// This is a more specialized version of protobuf.rpc.ServiceCallback
598598
"@typedef " + cbName,
599599
"@type {function}",
600-
"@param {?Error} error Error, if any",
600+
"@param {Error|null} error Error, if any",
601601
"@param {" + method.resolvedResponseType.fullName.substring(1) + "} [response] " + method.resolvedResponseType.name
602602
]);
603603
push("");

‎index.d.ts‎

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ export namespace common {
2424
* @param file Proto file name
2525
* @returns Root definition or `null` if not defined
2626
*/
27-
function get(file: string): INamespace;
27+
function get(file: string): (INamespace|null);
2828

2929
/** Properties of a google.protobuf.Any message. */
3030
interface IAny {
@@ -186,12 +186,12 @@ export class Enum extends ReflectionObject {
186186
* Adds a value to this enum.
187187
* @param name Value name
188188
* @param id Value id
189-
* @param comment Comment, if any
189+
* @param [comment] Comment, if any
190190
* @returns `this`
191191
* @throws {TypeError} If arguments are invalid
192192
* @throws {Error} If there is already a value with this name or id
193193
*/
194-
public add(name: string, id: number, comment: string): Enum;
194+
public add(name: string, id: number, comment?: string): Enum;
195195

196196
/**
197197
* Removes a value from this enum
@@ -298,10 +298,10 @@ export class FieldBase extends ReflectionObject {
298298
public map: boolean;
299299

300300
/** Message this field belongs to. */
301-
public message: Type;
301+
public message: (Type|null);
302302

303303
/** OneOf this field belongs to, if any, */
304-
public partOf: OneOf;
304+
public partOf: (OneOf|null);
305305

306306
/** The field type's default value. */
307307
public typeDefault: any;
@@ -316,13 +316,13 @@ export class FieldBase extends ReflectionObject {
316316
public bytes: boolean;
317317

318318
/** Resolved type if not a basic type. */
319-
public resolvedType: (Type|Enum);
319+
public resolvedType: (Type|Enum|null);
320320

321321
/** Sister-field within the extended type if a declaring extension field. */
322-
public extensionField: Field;
322+
public extensionField: (Field|null);
323323

324324
/** Sister-field within the declaring namespace if an extended field. */
325-
public declaringField: Field;
325+
public declaringField: (Field|null);
326326

327327
/**
328328
* Converts this field to a field descriptor.
@@ -373,7 +373,7 @@ type FieldDecorator = (prototype: object, fieldName: string) => void;
373373
* @param error Error, if any, otherwise `null`
374374
* @param [root] Root, if there hasn't been an error
375375
*/
376-
type LoadCallback = (error: Error, root?: Root) => void;
376+
type LoadCallback = (error: (Error|null), root?: Root) => void;
377377

378378
/**
379379
* 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 {
434434
public keyType: string;
435435

436436
/** Resolved key type if not a basic type. */
437-
public resolvedKeyType: ReflectionObject;
437+
public resolvedKeyType: (ReflectionObject|null);
438438

439439
/**
440440
* Constructs a map field from a map field descriptor.
@@ -532,7 +532,7 @@ export class Message<T extends object> {
532532
* @param message Plain object to verify
533533
* @returns `null` if valid, otherwise the reason why it is not
534534
*/
535-
public static verify(message: { [k: string]: any }): string;
535+
public static verify(message: { [k: string]: any }): (string|null);
536536

537537
/**
538538
* 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 {
587587
public responseStream?: boolean;
588588

589589
/** Resolved request type. */
590-
public resolvedRequestType: Type;
590+
public resolvedRequestType: (Type|null);
591591

592592
/** Resolved response type. */
593-
public resolvedResponseType: Type;
593+
public resolvedResponseType: (Type|null);
594594

595595
/**
596596
* Constructs a method from a method descriptor.
@@ -684,7 +684,7 @@ export abstract class NamespaceBase extends ReflectionObject {
684684
* @param name Nested object name
685685
* @returns The reflection object or `null` if it doesn't exist
686686
*/
687-
public get(name: string): ReflectionObject;
687+
public get(name: string): (ReflectionObject|null);
688688

689689
/**
690690
* Gets the values of the nested {@link Enum|enum} of the specified name.
@@ -734,15 +734,15 @@ export abstract class NamespaceBase extends ReflectionObject {
734734
* @param [parentAlreadyChecked=false] If known, whether the parent has already been checked
735735
* @returns Looked up object or `null` if none could be found
736736
*/
737-
public lookup(path: (string|string[]), filterTypes: (any|any[]), parentAlreadyChecked?: boolean): ReflectionObject;
737+
public lookup(path: (string|string[]), filterTypes: (any|any[]), parentAlreadyChecked?: boolean): (ReflectionObject|null);
738738

739739
/**
740740
* Looks up the reflection object at the specified path, relative to this namespace.
741741
* @param path Path to look up
742742
* @param [parentAlreadyChecked=false] Whether the parent has already been checked
743743
* @returns Looked up object or `null` if none could be found
744744
*/
745-
public lookup(path: (string|string[]), parentAlreadyChecked?: boolean): ReflectionObject;
745+
public lookup(path: (string|string[]), parentAlreadyChecked?: boolean): (ReflectionObject|null);
746746

747747
/**
748748
* Looks up the {@link Type|type} at the specified path, relative to this namespace.
@@ -807,16 +807,16 @@ export abstract class ReflectionObject {
807807
public name: string;
808808

809809
/** Parent namespace. */
810-
public parent: Namespace;
810+
public parent: (Namespace|null);
811811

812812
/** Whether already resolved or not. */
813813
public resolved: boolean;
814814

815815
/** Comment text, if any. */
816-
public comment: string;
816+
public comment: (string|null);
817817

818818
/** Defining file name. */
819-
public filename: string;
819+
public filename: (string|null);
820820

821821
/** Reference to the root namespace. */
822822
public readonly root: Root;
@@ -1173,7 +1173,7 @@ export class Root extends NamespaceBase {
11731173
* @param target The file name being imported
11741174
* @returns Resolved path to `target` or `null` to skip the file
11751175
*/
1176-
public resolvePath(origin: string, target: string): string;
1176+
public resolvePath(origin: string, target: string): (string|null);
11771177

11781178
/**
11791179
* Loads one or multiple .proto or preprocessed .json files into this root namespace and calls the callback.
@@ -1218,7 +1218,7 @@ export namespace rpc {
12181218
* @param error Error, if any
12191219
* @param [response] Response message
12201220
*/
1221-
type ServiceMethodCallback<TRes extends Message<TRes>> = (error: Error, response?: TRes) => void;
1221+
type ServiceMethodCallback<TRes extends Message<TRes>> = (error: (Error|null), response?: TRes) => void;
12221222

12231223
/**
12241224
* A service method part of a {@link rpc.Service} as created by {@link Service.create}.
@@ -1240,7 +1240,7 @@ export namespace rpc {
12401240
constructor(rpcImpl: RPCImpl, requestDelimited?: boolean, responseDelimited?: boolean);
12411241

12421242
/** RPC implementation. Becomes `null` once the service is ended. */
1243-
public rpcImpl: RPCImpl;
1243+
public rpcImpl: (RPCImpl|null);
12441244

12451245
/** Whether requests are length-delimited. */
12461246
public requestDelimited: boolean;
@@ -1280,7 +1280,7 @@ type RPCImpl = (method: (Method|rpc.ServiceMethod<Message<{}>, Message<{}>>), re
12801280
* @param error Error, if any, otherwise `null`
12811281
* @param [response] Response data or `null` to signal end of stream, if there hasn't been an error
12821282
*/
1283-
type RPCImplCallback = (error: Error, response?: Uint8Array) => void;
1283+
type RPCImplCallback = (error: (Error|null), response?: (Uint8Array|null)) => void;
12841284

12851285
/** Reflected service. */
12861286
export class Service extends NamespaceBase {
@@ -1335,13 +1335,13 @@ export interface IService extends INamespace {
13351335
* Gets the next token and advances.
13361336
* @returns Next token or `null` on eof
13371337
*/
1338-
type TokenizerHandleNext = () => string;
1338+
type TokenizerHandleNext = () => (string|null);
13391339

13401340
/**
13411341
* Peeks for the next token.
13421342
* @returns Next token or `null` on eof
13431343
*/
1344-
type TokenizerHandlePeek = () => string;
1344+
type TokenizerHandlePeek = () => (string|null);
13451345

13461346
/**
13471347
* Pushes a token back to the stack.
@@ -1363,7 +1363,7 @@ type TokenizerHandleSkip = (expected: string, optional?: boolean) => boolean;
13631363
* @param [line] Line number
13641364
* @returns Comment text or `null` if none
13651365
*/
1366-
type TokenizerHandleCmnt = (line?: number) => string;
1366+
type TokenizerHandleCmnt = (line?: number) => (string|null);
13671367

13681368
/** Handle object returned from {@link tokenize}. */
13691369
export interface ITokenizerHandle {
@@ -1547,7 +1547,7 @@ export class Type extends NamespaceBase {
15471547
* @param message Plain object to verify
15481548
* @returns `null` if valid, otherwise the reason why it is not
15491549
*/
1550-
public verify(message: { [k: string]: any }): string;
1550+
public verify(message: { [k: string]: any }): (null|string);
15511551

15521552
/**
15531553
* 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 {
23812381
public tail: object;
23822382

23832383
/** Linked forked states. */
2384-
public states: object;
2384+
public states: (object|null);
23852385

23862386
/**
23872387
* Creates a new writer.

‎src/common.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ function common(name, json) {
4242
* @name common.get
4343
* @function
4444
* @param {string} file Proto file name
45-
* @returns {?INamespace} Root definition or `null` if not defined
45+
* @returns {INamespace|null} Root definition or `null` if not defined
4646
*/
4747
common.get = function get(file) {
4848
return common[file] || null;

‎src/enum.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ Enum.prototype.toJSON = function toJSON() {
8383
* Adds a value to this enum.
8484
* @param {string} name Value name
8585
* @param {number} id Value id
86-
* @param {?string} comment Comment, if any
86+
* @param {string} [comment] Comment, if any
8787
* @returns {Enum} `this`
8888
* @throws {TypeError} If arguments are invalid
8989
* @throws {Error} If there is already a value with this name or id

‎src/field.js‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -125,13 +125,13 @@ function Field(name, id, type, rule, extend, options) {
125125

126126
/**
127127
* Message this field belongs to.
128-
* @type {?Type}
128+
* @type {Type|null}
129129
*/
130130
this.message = null;
131131

132132
/**
133133
* OneOf this field belongs to, if any,
134-
* @type {?OneOf}
134+
* @type {OneOf|null}
135135
*/
136136
this.partOf = null;
137137

@@ -161,25 +161,25 @@ function Field(name, id, type, rule, extend, options) {
161161

162162
/**
163163
* Resolved type if not a basic type.
164-
* @type {?(Type|Enum)}
164+
* @type {Type|Enum|null}
165165
*/
166166
this.resolvedType = null;
167167

168168
/**
169169
* Sister-field within the extended type if a declaring extension field.
170-
* @type {?Field}
170+
* @type {Field|null}
171171
*/
172172
this.extensionField = null;
173173

174174
/**
175175
* Sister-field within the declaring namespace if an extended field.
176-
* @type {?Field}
176+
* @type {Field|null}
177177
*/
178178
this.declaringField = null;
179179

180180
/**
181181
* Internally remembers whether this field is packed.
182-
* @type {?boolean}
182+
* @type {boolean|null}
183183
* @private
184184
*/
185185
this._packed = null;

‎src/index-light.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ protobuf.build = "light";
77
* A node-style callback as used by {@link load} and {@link Root#load}.
88
* @typedef LoadCallback
99
* @type {function}
10-
* @param {?Error} error Error, if any, otherwise `null`
10+
* @param {Error|null} error Error, if any, otherwise `null`
1111
* @param {Root} [root] Root, if there hasn't been an error
1212
* @returns {undefined}
1313
*/

‎src/mapfield.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ function MapField(name, id, keyType, type, options) {
3434

3535
/**
3636
* Resolved key type if not a basic type.
37-
* @type {?ReflectionObject}
37+
* @type {ReflectionObject|null}
3838
*/
3939
this.resolvedKeyType = null;
4040

‎src/message.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ Message.decodeDelimited = function decodeDelimited(reader) {
9999
* @name Message.verify
100100
* @function
101101
* @param {Object.<string,*>} message Plain object to verify
102-
* @returns {?string} `null` if valid, otherwise the reason why it is not
102+
* @returns {string|null} `null` if valid, otherwise the reason why it is not
103103
*/
104104
Message.verify = function verify(message) {
105105
return this.$type.verify(message);

‎src/method.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,13 @@ function Method(name, type, requestType, responseType, requestStream, responseSt
7777

7878
/**
7979
* Resolved request type.
80-
* @type {?Type}
80+
* @type {Type|null}
8181
*/
8282
this.resolvedRequestType = null;
8383

8484
/**
8585
* Resolved response type.
86-
* @type {?Type}
86+
* @type {Type|null}
8787
*/
8888
this.resolvedResponseType = null;
8989
}

‎src/namespace.js‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ function Namespace(name, options) {
7474

7575
/**
7676
* Cached nested objects as an array.
77-
* @type {?ReflectionObject[]}
77+
* @type {ReflectionObject[]|null}
7878
* @private
7979
*/
8080
this._nestedArray = null;
@@ -158,7 +158,7 @@ Namespace.prototype.addJSON = function addJSON(nestedJson) {
158158
/**
159159
* Gets the nested object of the specified name.
160160
* @param {string} name Nested object name
161-
* @returns {?ReflectionObject} The reflection object or `null` if it doesn't exist
161+
* @returns {ReflectionObject|null} The reflection object or `null` if it doesn't exist
162162
*/
163163
Namespace.prototype.get = function get(name) {
164164
return this.nested && this.nested[name]
@@ -285,7 +285,7 @@ Namespace.prototype.resolveAll = function resolveAll() {
285285
* @param {string|string[]} path Path to look up
286286
* @param {*|Array.<*>} filterTypes Filter types, any combination of the constructors of `protobuf.Type`, `protobuf.Enum`, `protobuf.Service` etc.
287287
* @param {boolean} [parentAlreadyChecked=false] If known, whether the parent has already been checked
288-
* @returns {?ReflectionObject} Looked up object or `null` if none could be found
288+
* @returns {ReflectionObject|null} Looked up object or `null` if none could be found
289289
*/
290290
Namespace.prototype.lookup = function lookup(path, filterTypes, parentAlreadyChecked) {
291291

@@ -334,7 +334,7 @@ Namespace.prototype.lookup = function lookup(path, filterTypes, parentAlreadyChe
334334
* @function
335335
* @param {string|string[]} path Path to look up
336336
* @param {boolean} [parentAlreadyChecked=false] Whether the parent has already been checked
337-
* @returns {?ReflectionObject} Looked up object or `null` if none could be found
337+
* @returns {ReflectionObject|null} Looked up object or `null` if none could be found
338338
* @variation 2
339339
*/
340340
// lookup(path: string, [parentAlreadyChecked: boolean])

0 commit comments

Comments
 (0)