aboutsummaryrefslogtreecommitdiffhomepage
path: root/src
diff options
context:
space:
mode:
authorGravatar Nicolas Noble <nicolasnoble@users.noreply.github.com>2015-07-28 08:37:34 -0700
committerGravatar Nicolas Noble <nicolasnoble@users.noreply.github.com>2015-07-28 08:37:34 -0700
commit8e06c2e62e0be2606598dd1f2a6582b585364520 (patch)
tree28e1805eaa5f38820f85c193984745d6b27c62cc /src
parentedf0881ca4aa0942a037b53071a2d03d45345722 (diff)
parent9cd90a64caaac14411b8c3d7a5431e39b94f5aaa (diff)
Merge pull request #2676 from murgatroid99/node_jsdoc
Add Node documentation generation
Diffstat (limited to 'src')
-rw-r--r--src/node/index.js32
-rw-r--r--src/node/jsdoc_conf.json22
-rw-r--r--src/node/package.json4
-rw-r--r--src/node/src/client.js25
-rw-r--r--src/node/src/common.js52
-rw-r--r--src/node/src/server.js45
6 files changed, 115 insertions, 65 deletions
diff --git a/src/node/index.js b/src/node/index.js
index d81e780443..b26ab35f2c 100644
--- a/src/node/index.js
+++ b/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;
diff --git a/src/node/jsdoc_conf.json b/src/node/jsdoc_conf.json
new file mode 100644
index 0000000000..876a8e19c6
--- /dev/null
+++ b/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
+ }
+ }
+}
diff --git a/src/node/package.json b/src/node/package.json
index 1caf158792..756d41b0af 100644
--- a/src/node/package.json
+++ b/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",
diff --git a/src/node/src/client.js b/src/node/src/client.js
index d89c656c07..f843669bd0 100644
--- a/src/node/src/client.js
+++ b/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
*/
diff --git a/src/node/src/common.js b/src/node/src/common.js
index feaa859a4f..5551ebeec8 100644
--- a/src/node/src/common.js
+++ b/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;
+};
diff --git a/src/node/src/server.js b/src/node/src/server.js
index e876313d96..9fbd1ee3bd 100644
--- a/src/node/src/server.js
+++ b/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;