Skip to content
Snippets Groups Projects
Commit 9cd90a64 authored by murgatroid99's avatar murgatroid99
Browse files

Rearranged some code for jsdoc, added some documentation

parent 46f2860b
Branches
Tags
No related merge requests found
Show whitespace changes
Inline Side-by-side
src/node/index.js
+ 13
− 19
View file @ 9cd90a64
......@@ -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/src/client.js
+ 14
− 11
View file @ 9cd90a64
......@@ -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) {
......@@ -503,7 +510,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
......@@ -552,7 +559,7 @@ function makeClientConstructor(methods, serviceName) {
});
return Client;
}
};
/**
* Creates a constructor for clients for the given service
......@@ -560,22 +567,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
+ 20
− 32
View file @ 9cd90a64
......@@ -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
+ 43
− 2
View file @ 9cd90a64
......@@ -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) {
......@@ -375,6 +396,7 @@ ServerDuplexStream.prototype.sendMetadata = sendMetadata;
/**
* 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
......@@ -426,6 +448,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
......@@ -454,6 +477,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
......@@ -488,6 +512,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
......@@ -571,7 +596,8 @@ function Server(options) {
}
server.requestCall(handleNewCall);
};
/** Shuts down the server.
/**
* Shuts down the server.
*/
this.shutdown = function() {
server.shutdown();
......@@ -605,6 +631,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.');
......@@ -642,6 +677,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);
};
......@@ -665,6 +706,6 @@ Server.prototype.bind = function(port, creds) {
};
/**
* See documentation for Server
* @see module:src/server~Server
*/
exports.Server = Server;
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please to comment