Commit ecf03e42 authored by Nick Kallen's avatar Nick Kallen

Better documentation

parent 7f9f3c42
......@@ -2,10 +2,12 @@ var git = require('../'),
TreeEntry = git.TreeEntry,
Blob = git.Blob;
var oldContent = Blob.prototype.content;
/**
* Replace old content method with something nicer.
* Retrieve the content of the blob.
* @return {Buffer} content
*/
var oldContent = Blob.prototype.content;
Blob.prototype.content = function() {
return oldContent.call(this).toBuffer(this.size());
};
......
......@@ -4,6 +4,7 @@ var git = require('../'),
/**
* Retrieve the SHA.
* @return {String}
*/
Commit.prototype.sha = function() {
return this.oid().sha();
......@@ -11,6 +12,7 @@ Commit.prototype.sha = function() {
/**
* Retrieve the commit time as a unix timestamp.
* @return {Number}
*/
Commit.prototype.timeMs = function() {
return this.time() * 1000;
......@@ -18,6 +20,7 @@ Commit.prototype.timeMs = function() {
/**
* Retrieve the commit time as a Date object.
* @return {Date}
*/
Commit.prototype.date = function() {
return new Date(this.timeMs());
......@@ -25,6 +28,7 @@ Commit.prototype.date = function() {
/**
* Get the tree associated with this commit.
* @return {Tree}
*/
Commit.prototype.getTree = function(callback) {
this.repo.getTree(this.treeId(), callback);
......@@ -35,14 +39,10 @@ Commit.prototype.getTree = function(callback) {
* Path must be relative to repository root.
*
* @param {String} path
* @param {Commit~fileCallback} callback
* @param {Function} callback
* @return {TreeEntry}
*/
Commit.prototype.getEntry = function(path, callback) {
/**
* @callback Commit~fileCallback Callback executed on file retrieval.
* @param {GitError|null} error An Error or null if successful.
* @param {Entry|null} file Retrieved file entry.
*/
this.getTree(function(error, tree) {
if (error) return callback(error);
......@@ -54,11 +54,12 @@ Commit.prototype.getEntry = function(path, callback) {
* Walk the history from this commit backwards.
* An EventEmitter is returned that will emit a 'commit' event for each
* commit in the history, and one 'end' event when the walk is completed.
* Don't forget to call `start()` on the returned event.
*
* @fires Commit#commit
* @fires Commit#end
*
* @return {EventEmitter} historyWalkEmitter
* @return {EventEmitter}
*/
Commit.prototype.history = function() {
var event = new events.EventEmitter();
......@@ -71,25 +72,9 @@ Commit.prototype.history = function() {
if (error) return event.emit('error', error);
if (!commit) {
/**
* End event.
*
* @event Commit#end
*
* @param {GitError|null} error An error object if there was an issue, null otherwise.
* @param {Commit[]} commits The commits.
*/
event.emit('end', commits);
return;
}
/**
* Commit event.
*
* @event Commit#commit
*
* @param {GitError|null} error An error object if there was an issue, null otherwise.
* @param {Commit} commit The commit.
*/
event.emit('commit', commit);
commits.push(commit);
});
......@@ -100,14 +85,10 @@ Commit.prototype.history = function() {
/**
* Retrieve the commit's parents -- as commit objects.
*
* @param {Commit~parentsCallback} callback
* @param {Function} callback
* @return {[Commit]} array of commits
*/
Commit.prototype.getParents = function(callback) {
/**
* @callback Commit~parentsCallback Callback executed on parents retrieval.
* @param {GitError|null} error An Error or null if successful.
* @param {Commit[]|null} parents Commit's parent(s).
*/
var self = this;
function processParents(commit, n, acc, callback) {
if (n < 0) return callback(null, acc);
......@@ -124,7 +105,8 @@ Commit.prototype.getParents = function(callback) {
/**
* Retrieve the commit's parent shas.
*
* @param {Commit~parentsCallback} callback
* @param {Function} callback
* @return {[Oid]} array of oids
*/
Commit.prototype.parents = function() {
var result = [];
......@@ -138,14 +120,10 @@ Commit.prototype.parents = function() {
* Generate an array of diff trees showing changes between this commit
* and its parent(s).
*
* @param {Commit~parentsDiffTreesCallback} callback
* @param {Function} callback
* @return {[DiffList]} an array of difflists
*/
Commit.prototype.getDiff = function(callback) {
/**
* @callback Commit~parentsDiffTreesCallback Callback executed on diff trees retrieval.
* @param {GitError|null} error An Error or null if successful.
* @param {DiffList[]|null} diffLists Array of DiffTrees showing changes between this commit and its parent(s)
*/
var self = this;
self.getParents(function commitParents(error, parents) {
if (error) return callback(error);
......@@ -172,6 +150,10 @@ Commit.prototype.getDiff = function(callback) {
});
};
/**
* The sha of this commit
* @return {String}
*/
Commit.prototype.toString = function() {
return this.sha();
};
......@@ -3,14 +3,27 @@ function ConvenientHunk(raw, i) {
this.i = i;
}
/**
* Diff header string that represents the context of this hunk
* of the diff. Something like `@@ -169,14 +167,12 @@ ...`
* @return {String}
*/
ConvenientHunk.prototype.header = function() {
return this.raw.hunk(this.i).header;
};
/**
* Number of lines in this hunk
* @return {Number}
*/
ConvenientHunk.prototype.size = function() {
return this.raw.hunk(this.i).lines;
};
/**
* The lines in this hunk
* @return {[String]} array of strings
*/
ConvenientHunk.prototype.lines = function() {
var result = [];
for (var i = 0; i < this.size(); i++)
......
......@@ -6,63 +6,119 @@ function ConvenientPatch(raw) {
this.raw = raw;
}
/**
* Old name of the file
* @return {String}
*/
ConvenientPatch.prototype.oldFile = function() {
return this.raw.delta.oldFile();
};
/**
* New name of the file
* @return {String}
*/
ConvenientPatch.prototype.newFile = function() {
return this.raw.delta.newFile();
};
/**
* The number of hunks in this patch
* @return {Number}
*/
ConvenientPatch.prototype.size = function() {
return this.raw.patch.size();
};
/**
* The hunks in this patch
* @return {[ConvenientHunk]} an array of ConvenientHunks
*/
ConvenientPatch.prototype.hunks = function() {
var result = [];
for (var i = 0; i < this.size(); i++)
result.push(new ConvenientHunk(this.raw.patch, i));
return result;
};
/**
* The status of this patch (unmodified, added, deleted)
* @return {Number}
*/
ConvenientPatch.prototype.status = function() {
return this.raw.delta.status();
};
/**
* Is this an unmodified patch?
* @return {Boolean}
*/
ConvenientPatch.prototype.isUnmodified = function() {
return this.status() == DiffList.Delta.Unmodified;
};
/**
* Is this an added patch?
* @return {Boolean}
*/
ConvenientPatch.prototype.isAdded = function() {
return this.status() == DiffList.Delta.Added;
};
/**
* Is this a deleted patch?
* @return {Boolean}
*/
ConvenientPatch.prototype.isDeleted = function() {
return this.status() == DiffList.Delta.Deleted;
};
/**
* Is this an modified patch?
* @return {Boolean}
*/
ConvenientPatch.prototype.isModified = function() {
return this.status() == DiffList.Delta.Modified;
};
/**
* Is this a renamed patch?
* @return {Boolean}
*/
ConvenientPatch.prototype.isRenamed = function() {
return this.status() == DiffList.Delta.Renamed;
};
/**
* Is this a copied patch?
* @return {Boolean}
*/
ConvenientPatch.prototype.isCopied = function() {
return this.status() == DiffList.Delta.Copied;
};
/**
* Is this an ignored patch?
* @return {Boolean}
*/
ConvenientPatch.prototype.isIgnored = function() {
return this.status() == DiffList.Delta.Ignored;
};
/**
* Is this an untracked patch?
* @return {Boolean}
*/
ConvenientPatch.prototype.isUntracked = function() {
return this.status() == DiffList.Delta.Untracked;
};
/**
* Is this a type change?
* @return {Boolean}
*/
ConvenientPatch.prototype.isTypeChange = function() {
return this.status() == DiffList.Delta.TypeChange;
};
ConvenientPatch.prototype.hunks = function() {
var result = [];
for (var i = 0; i < this.size(); i++)
result.push(new ConvenientHunk(this.raw.patch, i));
return result;
};
exports.ConvenientPatch = ConvenientPatch;
......@@ -39,9 +39,9 @@ DiffList.LineOrigin = {
};
/**
* Retrieve patches
* Retrieve patches in this difflist
*
* @return {Array} patches
* @return {[ConvenientPatch]} an array of ConvenientPatches
*/
DiffList.prototype.patches = function() {
var size = this.size();
......
......@@ -3,6 +3,7 @@ var git = require('../'),
/**
* Return an array of the entries in this index.
* @return {[IndexEntry]} an array of IndexEntrys
*/
Index.prototype.entries = function() {
var size = this.size(),
......
......@@ -13,18 +13,34 @@ git.Object.Type = {
OidDelta: 7 /**< A delta, base is given by object id. */
};
/**
* Is this object a commit?
* @return {Boolean}
*/
git.Object.prototype.isCommit = function() {
return this.type() == Object.Type.Commit;
};
/**
* Is this object a tree?
* @return {Boolean}
*/
git.Object.prototype.isTree = function() {
return this.type() == Object.Type.Tree;
};
/**
* Is this object a blob?
* @return {Boolean}
*/
git.Object.prototype.isBlob = function() {
return this.type() == Object.Type.Blob;
};
/**
* Is this object a tag?
* @return {Boolean}
*/
git.Object.prototype.isTag = function() {
return this.type() == Object.Type.Tag;
};
......@@ -6,7 +6,8 @@ var git = require('../'),
* Retrieve the object identified by oid.
*
* @param {String|Oid} String sha or Oid
* @param {Repo~commitCallback} callback
* @param {Function} callback
* @return {git.Object} a git odb object
*/
util.normalizeOid(Odb.prototype, 'read');
util.makeSafe(Odb.prototype, 'read');
var git = require('../'),
Oid = git.Oid;
/**
* The hex representation of the SHA
* @return {String}
*/
Oid.prototype.toString = function() {
return this.sha();
};
......
var git = require('../'),
Reference = git.Reference;
var oldSymbolicTarget = Reference.prototype.symbolicTarget,
oldTarget = Reference.prototype.target;
Reference.Type = {
Oid: 1,
Symbolic: 2,
......@@ -9,6 +12,7 @@ Reference.Type = {
/**
* Returns true if this reference is not symbolic
* @return {Boolean}
*/
Reference.prototype.isConcrete = function() {
return this.type() == Reference.Type.Oid;
......@@ -16,6 +20,7 @@ Reference.prototype.isConcrete = function() {
/**
* Returns true if this reference is symbolic
* @return {Boolean}
*/
Reference.prototype.isSymbolic = function() {
return this.type() == Reference.Type.Symbolic;
......@@ -23,9 +28,9 @@ Reference.prototype.isSymbolic = function() {
/**
* Returns the target of this symbolic reference.
* @return {Reference}
* @throws if the target is not symbolic.
*/
var oldSymbolicTarget = Reference.prototype.symbolicTarget;
Reference.prototype.symbolicTarget = function() {
if (!this.isSymbolic()) throw this.name() + " is not symbolic";
......@@ -34,15 +39,19 @@ Reference.prototype.symbolicTarget = function() {
/**
* Returns the oid of this non-symbolic reference.
* @return {Oid}
* @throws if the target is symbolic.
*/
var oldTarget = Reference.prototype.target;
Reference.prototype.target = function() {
if (!this.isConcrete()) throw this.name() + " is symbolic";
return oldTarget.call(this);
};
/**
* Returns the name of the reference.
* @return {String}
*/
Reference.prototype.toString = function() {
return this.name();
}
\ No newline at end of file
......@@ -4,18 +4,23 @@ var git = require('../'),
Tree = git.Tree,
Reference = git.Reference;
var oldGetReference = Repo.prototype.getReference,
oldGetCommit = Repo.prototype.getCommit,
oldBlob = Repo.prototype.getBlob,
oldGetTree = Repo.prototype.getTree,
oldGetTag = Repo.prototype.getTag,
oldCreateRevWalk = Repo.prototype.createRevWalk,
oldCreateCommit = Repo.prototype.createCommit,
oldCreateBlobFromBuffer = Repo.prototype.createBlobFromBuffer;
/**
* Look up a branch's most recent commit.
*
* @param {String} name Branch name, e.g. 'master'
* @param {Repo~branchCallback} callback
* @param {Function} callback
* @return {Branch}
*/
Repo.prototype.getBranch = function(name, callback) {
/**
* @callback Repo~branchCallback Callback executed when the branch is checked out.
* @param {GitError|null} error An Error or null if successful.
* @param {Commit|null} repo HEAD commit for the branch.
*/
var self = this;
this.getReference('refs/heads/' + name, function referenceLookupCallback(error, reference) {
if (error) return callback(error);
......@@ -33,9 +38,9 @@ util.makeSafe(Repo.prototype, 'getBranch');
* Lookup the reference with the given name.
*
* @param {String} name
* @param {Reference~lookupCallback} callback
* @param {Function} callback
* @return {Reference}
*/
var oldGetReference = Repo.prototype.getReference;
Repo.prototype.getReference = function(name, callback) {
var self = this;
oldGetReference.call(this, name, function(error, reference) {
......@@ -59,9 +64,9 @@ util.makeSafe(Repo.prototype, 'getReference');
* Retrieve the commit identified by oid.
*
* @param {String|Oid} String sha or Oid
* @param {Repo~commitCallback} callback
* @param {Function} callback
* @return {Commit}
*/
var oldGetCommit = Repo.prototype.getCommit;
Repo.prototype.getCommit = function(oid, callback) {
var self = this;
oldGetCommit.call(this, oid, function(error, commit) {
......@@ -77,9 +82,9 @@ util.makeSafe(Repo.prototype, 'getCommit');
* Retrieve the blob represented by the oid.
*
* @param {String|Oid} String sha or Oid
* @param {Blob~lookupCallback} callback
* @param {Function} callback
* @return {Blob}
*/
var oldBlob = Repo.prototype.getBlob;
Repo.prototype.getBlob = function(oid, callback) {
var self = this;
oldBlob.call(this, oid, function(error, blob) {
......@@ -92,12 +97,12 @@ util.normalizeOid(Repo.prototype, 'getBlob');
util.makeSafe(Repo.prototype, 'getBlob');
/**
* Retrieve the blob represented by the oid.
* Retrieve the tree represented by the oid.
*
* @param {String|Oid} String sha or Oid
* @param {Blob~lookupCallback} callback
* @param {Function} callback
* @return {Tree}
*/
var oldGetTree = Repo.prototype.getTree;
Repo.prototype.getTree = function(oid, callback) {
var self = this;
oldGetTree.call(this, oid, function(error, tree) {
......@@ -113,9 +118,9 @@ util.makeSafe(Repo.prototype, 'getTree');
* Retrieve the tag represented by the oid.
*
* @param {String|Oid} String sha or Oid
* @param {Blob~lookupCallback} callback
* @param {Function} callback
* @return {Tag}
*/
var oldGetTag = Repo.prototype.getTag;
Repo.prototype.getTag = function(oid, callback) {
var self = this;
oldGetTag.call(this, oid, callback);
......@@ -124,12 +129,13 @@ util.normalizeOid(Repo.prototype, 'getTag');
util.makeSafe(Repo.prototype, 'getTag');
/**
* Retrieve the blob represented by the oid.
* Instantiate a new revision walker for browsing the Repo's history.
* See also `Commit.prototype.history()`
*
* @param {String|Oid} String sha or Oid
* @param {Blob~lookupCallback} callback
* @param {Function} callback
* @return {RevWalk}
*/
var oldCreateRevWalk = Repo.prototype.createRevWalk;
Repo.prototype.createRevWalk = function() {
var revWalk = oldCreateRevWalk.call(this);
revWalk.repo = this;
......@@ -139,7 +145,8 @@ Repo.prototype.createRevWalk = function() {
/**
* Retrieve the master branch.
*
* @param {Blob~lookupCallback} callback
* @param {Function} callback
* @return {Branch}
*/
Repo.prototype.getMaster = function(callback) {
this.getBranch('master', callback);
......@@ -147,6 +154,7 @@ Repo.prototype.getMaster = function(callback) {
/**
* Create a commit
*
* @param {String} updateRef
* @param {Signature} author
* @param {Signature} commiter
......@@ -154,8 +162,8 @@ Repo.prototype.getMaster = function(callback) {
* @param {Tree|Oid|String} Tree
* @param {Array} parents
* @param {Function} callback
* @return {Oid} The oid of the commit
*/
var oldCreateCommit = Repo.prototype.createCommit;
Repo.prototype.createCommit = function(updateRef, author, committer, message, tree, parents, callback) {
if (tree instanceof Tree) {
oldCreateCommit.call(
......@@ -191,8 +199,8 @@ Repo.prototype.createCommit = function(updateRef, author, committer, message, tr
*
* @param {Buffer} buffer
* @param {Function} callback
* @return {Blob}
*/
var oldCreateBlobFromBuffer = Repo.prototype.createBlobFromBuffer;
Repo.prototype.createBlobFromBuffer = function(buffer, callback) {
oldCreateBlobFromBuffer.call(this, buffer, buffer.length, callback);
};
\ No newline at end of file
var git = require('../'),
RevWalk = git.RevWalk;
var oldSorting = RevWalk.prototype.sorting;
/**
* Refer to vendor/libgit2/include/git2/revwalk.h for sort definitions.
*/
......@@ -12,9 +14,11 @@ RevWalk.Sort = {
};
/**
* Set the sort order for the revwalk
* Set the sort order for the revwalk. This function takes variable arguments
* like `revwalk.sorting(git.RevWalk.Topological, git.RevWalk.Reverse).`
*
* @param {Number}
*/
var oldSorting = RevWalk.prototype.sorting;
RevWalk.prototype.sorting = function() {
var sort = 0;
for (var i = 0; i < arguments.length; i++)
......@@ -23,11 +27,12 @@ RevWalk.prototype.sorting = function() {
};
/**
* Walk the history from the given oid.
* Walk the history from the given oid. The callback is invoked for each commit;
* When the walk is over, the callback is invoked with `(null, null)`.
*
* @param {Oid} oid
* @param {Function} callback Callback accepting the following arguments:
* error, index, commit, noMoreCommits
* @param {Function} callback
* @return {Commit}
*/
RevWalk.prototype.walk = function(oid, callback) {
var self = this;
......
......@@ -3,6 +3,7 @@ var git = require('../'),
/**
* Standard string representation of an author.
* @return {String}
*/
Signature.prototype.toString = function() {
return this.name().toString() + " <" + this.email().toString() + ">";
......
......@@ -3,8 +3,15 @@ var git = require('../'),
events = require('events'),
path = require('path');
var oldEntryByIndex = Tree.prototype.entryByIndex,
oldEntryByName = Tree.prototype.entryByName,
oldGetEntry = Tree.prototype.getEntry;
/**
* Diff two trees
* @param {Tree} tree to diff against
* @param {Function} callback
* @return {DiffList}
*/
Tree.prototype.diff = function(that, callback) {
this.diffTree(this.repo, that, null, callback);
......@@ -14,8 +21,8 @@ Tree.prototype.diff = function(that, callback) {
* Get an entry at the ith position.
*
* @param {Number} i
* @return {TreeEntry}
*/
var oldEntryByIndex = Tree.prototype.entryByIndex;
Tree.prototype.entryByIndex = function(i) {
var entry = oldEntryByIndex.call(this, i);
entry.parent = this;
......@@ -23,11 +30,11 @@ Tree.prototype.entryByIndex = function(i) {
};
/**
* Get an entry by name:
* Get an entry by name; if the tree is a directory, the name is the filename.
*
* @param {String} name
* @return {TreeEntry}
*/
var oldEntryByName = Tree.prototype.entryByName;
Tree.prototype.entryByName = function(name) {
var entry = oldEntryByName.call(this, name);
entry.parent = this;
......@@ -35,11 +42,12 @@ Tree.prototype.entryByName = function(name) {
};
/**
* Get an entry at a path
* Get an entry at a path. Unlike by name, this takes a fully
* qualified path, like `/foo/bar/baz.javascript`
*
* @param {String} path
* @return {TreeEntry}
*/
var oldGetEntry = Tree.prototype.getEntry;
Tree.prototype.getEntry = function(path, callback) {
// FIXME: this method ought to implement the recursion directly, rather than
// rely on oldGetEntry, in order to ensure that `parent` pointers are direct.
......@@ -55,6 +63,7 @@ Tree.prototype.getEntry = function(path, callback) {
/**
* Return an array of the entries in this tree (excluding its children).
* @return {[TreeEntry]} an array of TreeEntrys
*/
Tree.prototype.entries = function() {
var size = this.size(),
......@@ -66,7 +75,7 @@ Tree.prototype.entries = function() {
};
/**
* Walk the tree.
* Recursively walk the tree in breadth-first order. Fires an event for each entry.
*
* @fires Tree#entry
* @fires Tree#end
......@@ -93,13 +102,6 @@ Tree.prototype.walk = function(blobsOnly) {
tree.entries().forEach(function (entry) {
if (!blobsOnly || entry.isFile()) {
/**
* Entry event.
*
* @event Tree#entry
*
* @param {Entry} entry The tree entry.
*/
event.emit('entry', entry);
entries.push(entry);
}
......@@ -121,14 +123,16 @@ Tree.prototype.walk = function(blobsOnly) {
};
/**
* Return the path of this tree.
* Return the path of this tree, like `/lib/foo/bar`
* @return {String}
*/
Tree.prototype.path = function(blobsOnly) {
return this.entry ? this.entry.path() : '';
};
/**
* Make builder
* Make builder. This is helpful for modifying trees.
* @return {TreeBuilder}
*/
var oldBuilder = Tree.prototype.builder;
Tree.prototype.builder = function() {
......
......@@ -6,7 +6,7 @@ var git = require('../'),
var oldInsert = TreeBuilder.prototype.insert;
/**
* Insert an object into this tree
* Insert an object into this tree by oid
*
* @param {String} filename
* @param {Oid} oid
......@@ -19,7 +19,7 @@ TreeBuilder.prototype.insert = function(filename, oid, filemode) {
};
/**