add doc for bulds collection + small api fixes

docs/developing-plugins/builds-collection.md

@@ -0,0 +1,50 @@
+
+## BuildsCollection()
+
+  Facade entity which accumulates operations with currently running and
+  db saved builds.
+
+## BuildsCollection.create(params:Object, [callback(err)]:Function)
+
+  Create build by running given project.
+  - `params.projectName` - project to build
+  - `params.withScmChangesOnly` - if true then build will be started only if
+  there is scm changes for project
+  - `params.queueQueued` - if true then currently queued project can be queued
+  again
+  - `params.initiator` - contains information about initiator of the build,
+  must contain `type` property e.g. when one build triggers another:
+  initiator: {type: 'build', id: 123, number: 10, project: {name: 'project1'}
+
+## BuildsCollection.cancel(id:Number, [callback(err)]:Function)
+
+  Cancel build by id.
+  Note that only queued build can be canceled currently.
+
+## BuildsCollection.get(id:Number, callback(err,build):Function)
+
+  Get build by id.
+
+## BuildsCollection.getLogLines(params:Object, callback(err,logLinesData):Function)
+
+  Get log lines for the given build.
+  - `params.buildId` - target build
+  - `params.from` - if set then lines from that number will be returned
+  - `params.to` - if set then lines to that number will be returned
+
+## BuildsCollection.getAvgBuildDuration(builds:Array.<Object>)
+
+  Calculate average build duration for the given builds.
+
+## BuildsCollection.getRecent(params:Object, callback(err,builds):Function)
+
+  Get builds sorted by date in descending order.
+  - `params.projectName` - optional project filter
+  - `params.status` - optional status filter, can be used only when
+  `params.projectName` is set. When used builds in the result will contain
+  only following fields: id, number, startDate, endDate
+
+## BuildsCollection.getDoneStreak(params:Object, callback(err,doneStreak):Function)
+
+  Get info about current done builds streak.
+  - `params.projectName` - optional project filter

lib/build.js

@@ -30,20 +30,56 @@ BuildsCollection.prototype._proxyDistributorEvent = function(source, dest) {
 	});
 };
 
+/**
+ * Create build by running given project.
+ * - `params.projectName` - project to build
+ * - `params.withScmChangesOnly` - if true then build will be started only if
+ * there is scm changes for project
+ * - `params.queueQueued` - if true then currently queued project can be queued
+ * again
+ * - `params.initiator` - contains information about initiator of the build,
+ * must contain `type` property e.g. when one build triggers another:
+ * initiator: {type: 'build', id: 123, number: 10, project: {name: 'project1'}
+ *
+ * @param {Object} params
+ * @param {Function} [callback(err)]
+ */
 BuildsCollection.prototype.create = function(params, callback) {
 	this.distributor.run(params, callback);
 };
 
-BuildsCollection.prototype.cancel = function(params, callback) {
-	this.distributor.cancel(params, callback);
+/**
+ * Cancel build by id.
+ * Note that only queued build can be canceled currently.
+ *
+ * @param {Number} id
+ * @param {Function} [callback(err)]
+ */
+BuildsCollection.prototype.cancel = function(id, callback) {
+	this.distributor.cancel(id, callback);
 };
 
+/**
+ * Get build by id.
+ *
+ * @param {Number} id
+ * @param {Function} callback(err,build)
+ */
 BuildsCollection.prototype.get = function(id, callback) {
 	this.db.builds.find({start: {id: id}}, function(err, builds) {
 		callback(err, builds && builds[0]);
 	});
 };
 
+/**
+ * Get log lines for the given build.
+ * - `params.buildId` - target build
+ * - `params.from` - if set then lines from that number will be returned
+ * - `params.to` - if set then lines to that number will be returned
+ *
+ * @param {Object} params
+ * @param {Function} callback(err,logLinesData)
+ */
 BuildsCollection.prototype.getLogLines = function(params, callback) {
 	var self = this;
 
@@ -95,6 +131,11 @@ BuildsCollection.prototype.getLogLinesTail = function(params, callback) {
 	);	
 };
 
+/**
+ * Calculate average build duration for the given builds.
+ *
+ * @param {Object[]} builds
+ */
 BuildsCollection.prototype.getAvgBuildDuration = function(builds) {
 	var durationsSum = _(builds).reduce(function(sum, build) {
 		return sum + (build.endDate - build.startDate);
@@ -102,6 +143,16 @@ BuildsCollection.prototype.getAvgBuildDuration = function(builds) {
 	return Math.round(durationsSum / builds.length);
 };
 
+/**
+ * Get builds sorted by date in descending order.
+ * - `params.projectName` - optional project filter
+ * - `params.status` - optional status filter, can be used only when
+ * `params.projectName` is set. When used builds in the result will contain
+ * only following fields: id, number, startDate, endDate
+ *
+ * @param {Object} params
+ * @param {Function} callback(err,builds)
+ */
 BuildsCollection.prototype.getRecent = function(params, callback) {
 	params.limit = params.limit || 20;
 	var self = this;
@@ -127,6 +178,13 @@ BuildsCollection.prototype.getRecent = function(params, callback) {
 	);
 };
 
+/**
+ * Get info about current done builds streak.
+ * - `params.projectName` - optional project filter
+ *
+ * @param {Object} params
+ * @param {Function} callback(err,doneStreak)
+ */
 BuildsCollection.prototype.getDoneStreak = function(params, callback) {
 	var self = this;
 

lib/distributor.js

@@ -286,17 +286,21 @@ Distributor.prototype._updateBuild = function(build, changes, callback) {
 	);
 };
 
-Distributor.prototype.cancel = function(params, callback) {
+Distributor.prototype.cancel = function(id, callback) {
+	callback = callback || function(err) {
+		if (err) logger.error('Error during cancel: ', err.stack || err);
+	};
 	var self = this;
+
 	Steppy(
 		function() {
 			var queueItemIndex = _(self.queue).findIndex(function(item) {
-				return item.build.id === params.buildId;
+				return item.build.id === id;
 			});
 
 			if (queueItemIndex === -1) {
 				throw new Error(
-					'Build with id "' + params.buildId + '" not found for cancel'
+					'Build with id "' + id + '" not found for cancel'
 				);
 			}
 
@@ -317,13 +321,12 @@ Distributor.prototype.cancel = function(params, callback) {
 };
 
 Distributor.prototype.run = function(params, callback) {
+	callback = callback || function(err) {
+		if (err) logger.error('Error during run: ', err.stack || err);
+	};
 	var self = this,
 		project;
-	callback = callback || function(err) {
-		if (err) {
-			logger.error('Error during run: ', err.stack || err);
-		}
-	};
+
 	Steppy(
 		function() {
 			project = _(self.projects.get(params.projectName)).clone();

package.json

@@ -11,6 +11,8 @@
     "dev": "gulp",
     "sync": "npm install && npm prune && bower install && bower prune",
     "docProjectsCollection": "dox --api --skipSingleStar < lib/project.js | sed '/^  - \\[ProjectsCollection/ d' > docs/developing-plugins/projects-collection.md",
+    "docBuildsCollection": "dox --api --skipSingleStar < lib/build.js | sed '/^  - \\[BuildsCollection/ d' > docs/developing-plugins/builds-collection.md",
+    "doc": "nrun docProjectsCollection && nrun docBuildsCollection",
     "buildJs": "r.js -o static/js/requirejs/buid.js",
     "buildClean": "rm static/index.html",
     "buildHtml": "jade views/index.jade --obj '{\"env\": \"production\"}' -o static/",

resources/builds.js

@@ -84,7 +84,7 @@ module.exports = function(app) {
 			function() {
 				var buildId = req.data.buildId;
 				logger.log('Cancel build: "%s"', buildId);
-				app.builds.cancel({buildId: buildId}, this.slot());
+				app.builds.cancel(buildId, this.slot());
 			},
 			function() {
 				res.send();

test/distributor/main.js

@@ -155,7 +155,7 @@ describe('Distributor main', function() {
 
 				var originalRunNext = distributor._runNext;
 				distributor._runNext = function() {
-					distributor.cancel({buildId: 1}, function(err) {
+					distributor.cancel(1, function(err) {
 						cancelError = err;
 					});
 					originalRunNext.apply(distributor, arguments);
@@ -198,7 +198,7 @@ describe('Distributor main', function() {
 
 				var originalRunNext = distributor._runNext;
 				distributor._runNext = function() {
-					distributor.cancel({buildId: 2}, function(err) {
+					distributor.cancel(2, function(err) {
 						cancelError = err;
 					});
 					originalRunNext.apply(distributor, arguments);