Merge pull request #2676 from murgatroid99/node_jsdoc

Add Node documentation generation

src/node/index.js

@@ -48,7 +48,7 @@ var grpc = require('bindings')('grpc');
  * @param {ProtoBuf.Reflect.Namespace} value The ProtoBuf object to load.
  * @return {Object<string, *>} The resulting gRPC object
  */
-function loadObject(value) {
+exports.loadObject = function loadObject(value) {
   var result = {};
   if (value.className === 'Namespace') {
     _.each(value.children, function(child) {
@@ -62,7 +62,9 @@ function loadObject(value) {
   } else {
     return value;
   }
-}
+};
+
+var loadObject = exports.loadObject;
 
 /**
  * Load a gRPC object from a .proto file.
@@ -71,7 +73,7 @@ function loadObject(value) {
  *     'json'. Defaults to 'proto'
  * @return {Object<string, *>} The resulting gRPC object
  */
-function load(filename, format) {
+exports.load = function load(filename, format) {
   if (!format) {
     format = 'proto';
   }
@@ -88,7 +90,7 @@ function load(filename, format) {
   }
 
   return loadObject(builder.ns);
-}
+};
 
 /**
  * Get a function that a client can use to update metadata with authentication
@@ -97,7 +99,7 @@ function load(filename, format) {
  * @param {Object} credential The credential object to use
  * @return {function(Object, callback)} Metadata updater function
  */
-function getGoogleAuthDelegate(credential) {
+exports.getGoogleAuthDelegate = function getGoogleAuthDelegate(credential) {
   /**
    * Update a metadata object with authentication information.
    * @param {string} authURI The uri to authenticate to
@@ -120,20 +122,10 @@ function getGoogleAuthDelegate(credential) {
       callback(null, metadata);
     });
   };
-}
-
-/**
- * See docs for loadObject
- */
-exports.loadObject = loadObject;
+};
 
 /**
- * See docs for load
- */
-exports.load = load;
-
-/**
- * See docs for Server
+ * @see module:src/server.Server
  */
 exports.Server = server.Server;
 
@@ -141,6 +133,7 @@ exports.Server = server.Server;
  * Status name to code number mapping
  */
 exports.status = grpc.status;
+
 /**
  * Call error name to code number mapping
  */
@@ -156,6 +149,7 @@ exports.Credentials = grpc.Credentials;
  */
 exports.ServerCredentials = grpc.ServerCredentials;
 
-exports.getGoogleAuthDelegate = getGoogleAuthDelegate;
-
+/**
+ * @see module:src/client.makeClientConstructor
+ */
 exports.makeGenericClientConstructor = client.makeClientConstructor;

src/node/jsdoc_conf.json

@@ -0,0 +1,22 @@
+{
+  "tags": {
+    "allowUnknownTags": true
+  },
+  "source": {
+    "include": [ "index.js", "src" ],
+    "includePattern": ".+\\.js(doc)?$",
+    "excludePattern": "(^|\\/|\\\\)_"
+  },
+  "opts": {
+    "package": "package.json",
+    "readme": "README.md"
+  },
+  "plugins": [],
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "default": {
+      "outputSourceFiles": true
+    }
+  }
+}

src/node/package.json

@@ -21,7 +21,8 @@
   },
   "scripts": {
     "lint": "node ./node_modules/jshint/bin/jshint src test examples interop index.js",
-    "test": "node ./node_modules/mocha/bin/mocha && npm run-script lint"
+    "test": "node ./node_modules/mocha/bin/mocha && npm run-script lint",
+    "gen_docs": "./node_modules/.bin/jsdoc -c jsdoc_conf.json"
   },
   "dependencies": {
     "bindings": "^1.2.0",
@@ -32,6 +33,7 @@
   "devDependencies": {
     "async": "^0.9.0",
     "google-auth-library": "^0.9.2",
+    "jsdoc": "^3.3.2",
     "jshint": "^2.5.0",
     "minimist": "^1.1.0",
     "mocha": "~1.21.0",

src/node/src/client.js

@@ -31,6 +31,11 @@
  *
  */
 
+/**
+ * Server module
+ * @module
+ */
+
 'use strict';
 
 var _ = require('lodash');
@@ -72,6 +77,7 @@ function ClientWritableStream(call, serialize) {
 /**
  * Attempt to write the given chunk. Calls the callback when done. This is an
  * implementation of a method needed for implementing stream.Writable.
+ * @access private
  * @param {Buffer} chunk The chunk to write
  * @param {string} encoding Ignored
  * @param {function(Error=)} callback Called when the write is complete
@@ -110,6 +116,7 @@ function ClientReadableStream(call, deserialize) {
 
 /**
  * Read the next object from the stream.
+ * @access private
  * @param {*} size Ignored because we use objectMode=true
  */
 function _read(size) {
@@ -519,7 +526,7 @@ var requester_makers = {
  * @param {string} serviceName The name of the service
  * @return {function(string, Object)} New client constructor
  */
-function makeClientConstructor(methods, serviceName) {
+exports.makeClientConstructor = function(methods, serviceName) {
   /**
    * Create a client with the given methods
    * @constructor
@@ -568,7 +575,7 @@ function makeClientConstructor(methods, serviceName) {
   });
 
   return Client;
-}
+};
 
 /**
  * Creates a constructor for clients for the given service
@@ -576,22 +583,18 @@ function makeClientConstructor(methods, serviceName) {
  *     for
  * @return {function(string, Object)} New client constructor
  */
-function makeProtobufClientConstructor(service) {
+exports.makeProtobufClientConstructor =  function(service) {
   var method_attrs = common.getProtobufServiceAttrs(service, service.name);
-  var Client = makeClientConstructor(method_attrs);
+  var Client = exports.makeClientConstructor(method_attrs);
   Client.service = service;
-
   return Client;
-}
-
-exports.makeClientConstructor = makeClientConstructor;
-
-exports.makeProtobufClientConstructor = makeProtobufClientConstructor;
+};
 
 /**
- * See docs for client.status
+ * Map of status code names to status codes
  */
 exports.status = grpc.status;
+
 /**
  * See docs for client.callError
  */

src/node/src/common.js

@@ -31,6 +31,10 @@
  *
  */
 
+/**
+ * @module
+ */
+
 'use strict';
 
 var _ = require('lodash');
@@ -40,7 +44,7 @@ var _ = require('lodash');
  * @param {function()} cls The constructor of the message type to deserialize
  * @return {function(Buffer):cls} The deserialization function
  */
-function deserializeCls(cls) {
+exports.deserializeCls = function deserializeCls(cls) {
   /**
    * Deserialize a buffer to a message object
    * @param {Buffer} arg_buf The buffer to deserialize
@@ -51,14 +55,16 @@ function deserializeCls(cls) {
     // and longs as strings (second argument)
     return cls.decode(arg_buf).toRaw(false, true);
   };
-}
+};
+
+var deserializeCls = exports.deserializeCls;
 
 /**
  * Get a function that serializes objects to a buffer by protobuf class.
  * @param {function()} Cls The constructor of the message type to serialize
  * @return {function(Cls):Buffer} The serialization function
  */
-function serializeCls(Cls) {
+exports.serializeCls = function serializeCls(Cls) {
   /**
    * Serialize an object to a Buffer
    * @param {Object} arg The object to serialize
@@ -67,14 +73,16 @@ function serializeCls(Cls) {
   return function serialize(arg) {
     return new Buffer(new Cls(arg).encode().toBuffer());
   };
-}
+};
+
+var serializeCls = exports.serializeCls;
 
 /**
  * Get the fully qualified (dotted) name of a ProtoBuf.Reflect value.
  * @param {ProtoBuf.Reflect.Namespace} value The value to get the name of
  * @return {string} The fully qualified name of the value
  */
-function fullyQualifiedName(value) {
+exports.fullyQualifiedName = function fullyQualifiedName(value) {
   if (value === null || value === undefined) {
     return '';
   }
@@ -89,7 +97,9 @@ function fullyQualifiedName(value) {
     }
   }
   return name;
-}
+};
+
+var fullyQualifiedName = exports.fullyQualifiedName;
 
 /**
  * Wrap a function to pass null-like values through without calling it. If no
@@ -97,7 +107,7 @@ function fullyQualifiedName(value) {
  * @param {?function} func The function to wrap
  * @return {function} The wrapped function
  */
-function wrapIgnoreNull(func) {
+exports.wrapIgnoreNull = function wrapIgnoreNull(func) {
   if (!func) {
     return _.identity;
   }
@@ -107,14 +117,14 @@ function wrapIgnoreNull(func) {
     }
     return func(arg);
   };
-}
+};
 
 /**
  * Return a map from method names to method attributes for the service.
  * @param {ProtoBuf.Reflect.Service} service The service to get attributes for
  * @return {Object} The attributes map
  */
-function getProtobufServiceAttrs(service) {
+exports.getProtobufServiceAttrs = function getProtobufServiceAttrs(service) {
   var prefix = '/' + fullyQualifiedName(service) + '/';
   return _.object(_.map(service.children, function(method) {
     return [_.camelCase(method.name), {
@@ -127,26 +137,4 @@ function getProtobufServiceAttrs(service) {
       responseDeserialize: deserializeCls(method.resolvedResponseType.build())
     }];
   }));
-}
-
-/**
- * See docs for deserializeCls
- */
-exports.deserializeCls = deserializeCls;
-
-/**
- * See docs for serializeCls
- */
-exports.serializeCls = serializeCls;
-
-/**
- * See docs for fullyQualifiedName
- */
-exports.fullyQualifiedName = fullyQualifiedName;
-
-/**
- * See docs for wrapIgnoreNull
- */
-exports.wrapIgnoreNull = wrapIgnoreNull;
-
-exports.getProtobufServiceAttrs = getProtobufServiceAttrs;
+};

src/node/src/server.js

@@ -31,6 +31,11 @@
  *
  */
 
+/**
+ * Server module
+ * @module
+ */
+
 'use strict';
 
 var _ = require('lodash');
@@ -50,6 +55,7 @@ var EventEmitter = require('events').EventEmitter;
 
 /**
  * Handle an error on a call by sending it as a status
+ * @access private
  * @param {grpc.Call} call The call to send the error on
  * @param {Object} error The error object
  */
@@ -82,6 +88,7 @@ function handleError(call, error) {
 /**
  * Wait for the client to close, then emit a cancelled event if the client
  * cancelled.
+ * @access private
  * @param {grpc.Call} call The call object to wait on
  * @param {EventEmitter} emitter The event emitter to emit the cancelled event
  *     on
@@ -102,6 +109,7 @@ function waitForCancel(call, emitter) {
 
 /**
  * Send a response to a unary or client streaming call.
+ * @access private
  * @param {grpc.Call} call The call to respond on
  * @param {*} value The value to respond with
  * @param {function(*):Buffer=} serialize Serialization function for the
@@ -130,6 +138,7 @@ function sendUnaryResponse(call, value, serialize, metadata) {
 /**
  * Initialize a writable stream. This is used for both the writable and duplex
  * stream constructors.
+ * @access private
  * @param {Writable} stream The stream to set up
  * @param {function(*):Buffer=} Serialization function for responses
  */
@@ -203,6 +212,7 @@ function setUpWritable(stream, serialize) {
 /**
  * Initialize a readable stream. This is used for both the readable and duplex
  * stream constructors.
+ * @access private
  * @param {Readable} stream The stream to initialize
  * @param {function(Buffer):*=} deserialize Deserialization function for
  *     incoming data.
@@ -242,6 +252,7 @@ function ServerWritableStream(call, serialize) {
 /**
  * Start writing a chunk of data. This is an implementation of a method required
  * for implementing stream.Writable.
+ * @access private
  * @param {Buffer} chunk The chunk of data to write
  * @param {string} encoding Ignored
  * @param {function(Error=)} callback Callback to indicate that the write is
@@ -266,6 +277,11 @@ function _write(chunk, encoding, callback) {
 
 ServerWritableStream.prototype._write = _write;
 
+/**
+ * Send the initial metadata for a writable stream.
+ * @param {Object<String, Array<(String|Buffer)>>} responseMetadata Metadata
+ *   to send
+ */
 function sendMetadata(responseMetadata) {
   /* jshint validthis: true */
   if (!this.call.metadataSent) {
@@ -281,6 +297,10 @@ function sendMetadata(responseMetadata) {
   }
 }
 
+/**
+ * @inheritdoc
+ * @alias module:src/server~ServerWritableStream#sendMetadata
+ */
 ServerWritableStream.prototype.sendMetadata = sendMetadata;
 
 util.inherits(ServerReadableStream, Readable);
@@ -301,6 +321,7 @@ function ServerReadableStream(call, deserialize) {
 /**
  * Start reading from the gRPC data source. This is an implementation of a
  * method required for implementing stream.Readable
+ * @access private
  * @param {number} size Ignored
  */
 function _read(size) {
@@ -388,6 +409,7 @@ ServerDuplexStream.prototype.getPeer = getPeer;
 
 /**
  * Fully handle a unary call
+ * @access private
  * @param {grpc.Call} call The call to handle
  * @param {Object} handler Request handler object for the method that was called
  * @param {Object} metadata Metadata from the client
@@ -442,6 +464,7 @@ function handleUnary(call, handler, metadata) {
 
 /**
  * Fully handle a server streaming call
+ * @access private
  * @param {grpc.Call} call The call to handle
  * @param {Object} handler Request handler object for the method that was called
  * @param {Object} metadata Metadata from the client
@@ -470,6 +493,7 @@ function handleServerStreaming(call, handler, metadata) {
 
 /**
  * Fully handle a client streaming call
+ * @access private
  * @param {grpc.Call} call The call to handle
  * @param {Object} handler Request handler object for the method that was called
  * @param {Object} metadata Metadata from the client
@@ -504,6 +528,7 @@ function handleClientStreaming(call, handler, metadata) {
 
 /**
  * Fully handle a bidirectional streaming call
+ * @access private
  * @param {grpc.Call} call The call to handle
  * @param {Object} handler Request handler object for the method that was called
  * @param {Object} metadata Metadata from the client
@@ -587,7 +612,8 @@ function Server(options) {
     }
     server.requestCall(handleNewCall);
   };
-  /** Shuts down the server.
+  /**
+   * Shuts down the server.
    */
   this.shutdown = function() {
     server.shutdown();
@@ -621,6 +647,15 @@ Server.prototype.register = function(name, handler, serialize, deserialize,
   return true;
 };
 
+/**
+ * Add a service to the server, with a corresponding implementation. If you are
+ * generating this from a proto file, you should instead use
+ * addProtoService.
+ * @param {Object<String, *>} service The service descriptor, as
+ *     {@link module:src/common.getProtobufServiceAttrs} returns
+ * @param {Object<String, function>} implementation Map of method names to
+ *     method implementation for the provided service.
+ */
 Server.prototype.addService = function(service, implementation) {
   if (this.started) {
     throw new Error('Can\'t add a service to a started server.');
@@ -658,6 +693,12 @@ Server.prototype.addService = function(service, implementation) {
   });
 };
 
+/**
+ * Add a proto service to the server, with a corresponding implementation
+ * @param {Protobuf.Reflect.Service} service The proto service descriptor
+ * @param {Object<String, function>} implementation Map of method names to
+ *     method implementation for the provided service.
+ */
 Server.prototype.addProtoService = function(service, implementation) {
   this.addService(common.getProtobufServiceAttrs(service), implementation);
 };
@@ -681,6 +722,6 @@ Server.prototype.bind = function(port, creds) {
 };
 
 /**
- * See documentation for Server
+ * @see module:src/server~Server
  */
 exports.Server = Server;