Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add some docs

  • Loading branch information...
commit 36f36806c5dfbd686cc018e83ac124ffe18de7fc 1 parent a387836
Arjan van der Gaag authored
1  .gitignore
View
@@ -1 +1,2 @@
node_modules
+docs
2  lib/authentication_buffer.js
View
@@ -1,4 +1,6 @@
module.exports = (function() {
+ // An AuthenticationBuffer joins a username and password into an encoded
+ // string suitable for use with HTTP authentication headers.
function AuthenticationBuffer(username, password) {
this.auth_string = '' + username + ':' + password;
}
32 lib/heroku.js
View
@@ -3,9 +3,8 @@ module.exports = (function() {
AuthenticationBuffer = require('lib/authentication_buffer'),
JsonData = require('lib/json_data');
- /**
- * Constructor function
- */
+ // Constructor function that requires an `options` object with at least the
+ // `api_token` and `app` keys. Any other values are ignored.
function Heroku(options) {
if(!options.api_token) throw new Error('API token required');
if(!options.app) throw new Error('Application name required');
@@ -13,10 +12,12 @@ module.exports = (function() {
this.app = options.app;
}
- /**
- * Internal utility function to actually make the HTTP requests against the
- * Heroku API.
- */
+ // Internal utility function to actually make the HTTP requests against the
+ // Heroku API using a set of standard request options, parsing the repsonse
+ // body as JSON.
+ //
+ // Note how a special header is added to the request to set the Heroku client
+ // gem version. Without this value, Heroku will misbehave.
Heroku.prototype.request = function(path, fn) {
var options = {
host: 'api.heroku.com',
@@ -28,6 +29,10 @@ module.exports = (function() {
'Authorization': 'Basic'
}
};
+
+ // Make the request, accumulate any response data into a `JsonData`
+ // container and return it either as the error or data object to the given
+ // callback function -- depending on the HTTP status code.
http.request(options, function(response) {
var json_response = new JsonData();
response.setEncoding('utf-8');
@@ -45,18 +50,15 @@ module.exports = (function() {
}).end();
};
- /**
- * Generate a subpath local to an application root path on the Heroku API.
- */
+ // Generate a subpath local to an application root path on the Heroku API.
+ // For internal use only.
Heroku.prototype.appPath = function(subpath) {
return '/apps/' + this.app + '/' + subpath;
};
- /**
- * Load the value for a given environment variable on the current
- * application. The results are cached locally, so only a single request will
- * be made.
- */
+ // Load the value for a given environment variable on the current
+ // application. The results are cached locally, so only a single request will
+ // be made.
Heroku.prototype.config = function(key, fn) {
var that = this;
if(this._config_cache) {
12 lib/json_data.js
View
@@ -1,21 +1,33 @@
module.exports = (function() {
+ // Utility function to enable binding a given function to a given context --
+ // making using object methods as callbacks easier.
var bind = function(fn, context) {
return function() {
fn.apply(context, arguments);
};
};
+ // The JsonData object accumulates HTTP response data and parses the data as
+ // JSON, returning the result, when you're done.
+ //
+ // You can start, should you want to, with an initial value (defaults to an
+ // empty string).
function JsonData(initial) {
if(!initial) initial = '';
this.data = initial;
this.push = bind(this.push, this);
}
+
+ // Add more data to the internal container.
JsonData.prototype.push = function(data) {
this.data += data;
};
+
+ // Parse the current data contents as JSON.
JsonData.prototype.toJSON = function() {
return JSON.parse(this.data);
};
+
return JsonData;
})();
3  package.json
View
@@ -12,6 +12,7 @@
"devDependencies": {
"expect.js": "*",
"mocha": "*",
- "nock": "*"
+ "nock": "*",
+ "docco": "*"
}
}
Please sign in to comment.
Something went wrong with that request. Please try again.