From 8c8dc4c5cf795e6f9a3111487d2643665dfe2b09 Mon Sep 17 00:00:00 2001 From: Steve Smith Date: Sun, 22 Feb 2015 21:23:59 -0500 Subject: [PATCH] Update jsdoc and ignore some methods --- generate/input/descriptor.json | 37 ++++++++++++++++++++++++++++ lib/blob.js | 8 +++--- lib/checkout.js | 14 +++++++---- lib/clone.js | 8 +++--- lib/commit.js | 29 +++++++++++++--------- lib/index.js | 2 +- lib/merge.js | 8 +++--- lib/reference.js | 2 ++ lib/remote.js | 1 + lib/repository.js | 45 ++++++++++++++++++++++------------ lib/revwalk.js | 6 ++--- lib/tag.js | 2 +- lib/tree.js | 7 ++++-- lib/tree_entry.js | 2 ++ 14 files changed, 122 insertions(+), 49 deletions(-) diff --git a/generate/input/descriptor.json b/generate/input/descriptor.json index 9520f0577..84a01c861 100644 --- a/generate/input/descriptor.json +++ b/generate/input/descriptor.json @@ -71,6 +71,13 @@ }, "types": { + "annotated": { + "functions": { + "git_annotated_commit_free": { + "ignore": true + } + } + }, "attr": { "functions": { "git_attr_foreach": { @@ -83,6 +90,14 @@ "isReturn": true } } + }, + "git_attr_get_many": { + "args": { + "values_out": { + "isReturn": true, + "jsClassName": "Array" + } + } } } }, @@ -126,6 +141,9 @@ }, "branch": { "functions": { + "git_branch_iterator_free": { + "ignore": true + }, "git_branch_create": { "args": { "force": { @@ -853,6 +871,9 @@ }, "note": { "functions": { + "git_note_iterator_free": { + "ignore": true + }, "git_note_create": { "args": { "out": { @@ -1096,6 +1117,9 @@ }, "pathspec": { "functions": { + "git_pathspec_match_list_free": { + "ignore": true + }, "git_pathspec_new": { "ignore": true } @@ -1344,6 +1368,9 @@ }, "repository": { "functions": { + "git_repository_init_init_options": { + "ignore": true + }, "git_repository_discover": { "ignore": true }, @@ -1364,6 +1391,13 @@ } } }, + "revert": { + "functions": { + "git_revert_init_options": { + "ignore": true + } + } + }, "revparse": { "functions": { "git_revparse": { @@ -1542,6 +1576,9 @@ }, "tree": { "functions": { + "git_tree_entry_free": { + "ignore": true + }, "git_tree_entry_byindex": { "jsFunctionName": "_entryByIndex" }, diff --git a/lib/blob.js b/lib/blob.js index 842f2e114..a67c0adc6 100644 --- a/lib/blob.js +++ b/lib/blob.js @@ -6,9 +6,9 @@ var Blob = NodeGit.Blob; /** * Retrieves the blob pointed to by the oid +* @async * @param {Repository} repo The repo that the blob lives in * @param {String|Oid|Blob} id The blob to lookup -* @param {Function} callback * @return {Blob} */ Blob.lookup = LookupWrapper(Blob); @@ -16,7 +16,7 @@ Blob.lookup = LookupWrapper(Blob); /** * Retrieve the content of the Blob. * - * @return {Buffer} Contents. + * @return {Buffer} Contents as a buffer. */ Blob.prototype.content = function() { return this.rawcontent().toBuffer(this.rawsize()); @@ -25,7 +25,7 @@ Blob.prototype.content = function() { /** * Retrieve the Blob's content as String. * - * @return {string} Contents. + * @return {String} Contents as a string. */ Blob.prototype.toString = function() { return this.content().toString(); @@ -34,7 +34,7 @@ Blob.prototype.toString = function() { /** * Retrieve the Blob's type. * - * @return {number} The filemode. + * @return {Number} The filemode of the blob. */ Blob.prototype.filemode = function() { var FileMode = TreeEntry.FILEMODE; diff --git a/lib/checkout.js b/lib/checkout.js index aa07b385b..e3c05f8ce 100644 --- a/lib/checkout.js +++ b/lib/checkout.js @@ -8,8 +8,10 @@ var tree = Checkout.tree; /** * Patch head checkout to automatically coerce objects. * -* @param url -* @param options +* @async +* @param {Repository} repo The repo to checkout head +* @param {CheckoutOptions} [options] Options for the checkout +* @return {Void} checkout complete */ Checkout.head = function(url, options) { options = normalizeOptions(options, NodeGit.CheckoutOptions); @@ -20,9 +22,11 @@ Checkout.head = function(url, options) { /** * Patch tree checkout to automatically coerce objects. * -* @param repo -* @param treeish -* @param options +* @async +* @param {Repository} repo +* @param {Oid|Tree|Commit|Reference} treeish +* @param {CheckoutOptions} [options] +* @return {Void} checkout complete */ Checkout.tree = function(repo, treeish, options) { options = normalizeOptions(options, NodeGit.CheckoutOptions); diff --git a/lib/clone.js b/lib/clone.js index 500a455e2..7b6fefcfb 100644 --- a/lib/clone.js +++ b/lib/clone.js @@ -7,9 +7,11 @@ var clone = Clone.clone; /** * Patch repository cloning to automatically coerce objects. * - * @param url - * @param local_path - * @param options + * @async + * @param {String} url url of the repository + * @param {String} local_path local path to store repository + * @param {CloneOptions} [options] + * @return {Repository} repo */ Clone.clone = function(url, local_path, options) { var remoteCallbacks; diff --git a/lib/commit.js b/lib/commit.js index 399143402..20cd3ae0a 100644 --- a/lib/commit.js +++ b/lib/commit.js @@ -7,9 +7,9 @@ var Commit = NodeGit.Commit; /** * Retrieves the commit pointed to by the oid + * @async * @param {Repository} repo The repo that the commit lives in * @param {String|Oid|Commit} id The commit to lookup - * @param {Function} callback * @return {Commit} */ Commit.lookup = LookupWrapper(Commit); @@ -41,7 +41,7 @@ Commit.prototype.date = function() { /** * Get the tree associated with this commit. * - * @param {Function} callback + * @async * @return {Tree} */ Commit.prototype.getTree = function(callback) { @@ -52,8 +52,8 @@ Commit.prototype.getTree = function(callback) { * Retrieve the entry represented by path for this commit. * Path must be relative to repository root. * + * @async * @param {String} path - * @param {Function} callback * @return {TreeEntry} */ Commit.prototype.getEntry = function(path, callback) { @@ -68,16 +68,20 @@ Commit.prototype.getEntry = function(path, callback) { }, 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. + * Don't forget to call `start()` on the returned event. * - * @fires Commit#commit - * @fires Commit#end + * @fires EventEmitter#commit Commit + * @fires EventEmitter#end Array + * @fires EventEmitter#error Error * * @return {EventEmitter} + * @start start() */ Commit.prototype.history = function() { var event = new events.EventEmitter(); @@ -107,12 +111,14 @@ Commit.prototype.history = function() { return event; }; + /** - * Retrieve the commit"s parents -- as commit objects. + * Retrieve the commit's parents as commit objects. * - * @param {number} limit - Optional amount of parents to return. + * @async + * @param {number} limit Optional amount of parents to return. * @param {Function} callback - * @return {[Commit]} array of commits + * @return {Array} array of commits */ Commit.prototype.getParents = function(limit, callback) { var parents = []; @@ -147,7 +153,7 @@ Commit.prototype.getParents = function(limit, callback) { * Retrieve the commit"s parent shas. * * @param {Function} callback - * @return {[Oid]} array of oids + * @return {Array} array of oids */ Commit.prototype.parents = function() { var result = []; @@ -163,8 +169,9 @@ Commit.prototype.parents = function() { * Generate an array of diff trees showing changes between this commit * and its parent(s). * + * @async * @param {Function} callback - * @return {[Diff]} an array of diffs + * @return {Array} an array of diffs */ Commit.prototype.getDiff = function(callback) { var commit = this; diff --git a/lib/index.js b/lib/index.js index a5ed5b344..8986985e9 100644 --- a/lib/index.js +++ b/lib/index.js @@ -4,7 +4,7 @@ var Index = NodeGit.Index; /** * Return an array of the entries in this index. - * @return {[IndexEntry]} an array of IndexEntrys + * @return {Array} an array of IndexEntrys */ Index.prototype.entries = function() { var size = this.entryCount(); diff --git a/lib/merge.js b/lib/merge.js index fb9a8b0b5..8e83c09a3 100644 --- a/lib/merge.js +++ b/lib/merge.js @@ -9,10 +9,10 @@ var mergeCommits = Merge.commits; * Merge 2 commits together and create an new index that can * be used to create a merge commit. * - * @param repo Repository that contains the given commits - * @param ourCommit The commit that reflects the destination tree - * @oaram theirCommit The commit to merge into ourCommit - * @param options The merge tree options (null for default) + * @param {Repository} repo Repository that contains the given commits + * @param {Commit} ourCommit The commit that reflects the destination tree + * @param {Commit} theirCommit The commit to merge into ourCommit + * @param {MergeOptions} [options] The merge tree options (null for default) */ Merge.commits = function(repo, ourCommit, theirCommit, options) { options = normalizeOptions(options, NodeGit.MergeOptions); diff --git a/lib/reference.js b/lib/reference.js index c772239fd..437a61ec8 100644 --- a/lib/reference.js +++ b/lib/reference.js @@ -6,6 +6,7 @@ var Branch = NodeGit.Branch; /** * Retrieves the reference pointed to by the oid +* @async * @param {Repository} repo The repo that the reference lives in * @param {String|Reference} id The reference to lookup * @param {Function} callback @@ -15,6 +16,7 @@ Reference.lookup = LookupWrapper(Reference); /** * Retrieves the reference by it's short name +* @async * @param {Repository} repo The repo that the reference lives in * @param {String|Reference} id The reference to lookup * @param {Function} callback diff --git a/lib/remote.js b/lib/remote.js index c44ce1157..3b05b98d3 100644 --- a/lib/remote.js +++ b/lib/remote.js @@ -7,6 +7,7 @@ var setCallbacks = Remote.prototype.setCallbacks; /** * Retrieves the remote by name + * @async * @param {Repository} repo The repo that the remote lives in * @param {String|Remote} name The remote to lookup * @param {Function} callback diff --git a/lib/repository.js b/lib/repository.js index ec7b8cdfe..07e5fd252 100644 --- a/lib/repository.js +++ b/lib/repository.js @@ -22,6 +22,7 @@ Object.defineProperty(Repository.prototype, "openIndex", { /** * Creates a branch with the passed in name pointing to the commit * + * @async * @param {String} name Branch name, e.g. "master" * @param {Commit|String|Oid} commit The commit the branch will point to * @param {bool} force Overwrite branch if it exists @@ -58,9 +59,9 @@ function(name, commit, force, signature, logMessage) { /** * Look up a refs's commit. * + * @async * @param {String|Ref} name Ref name, e.g. "master", "refs/heads/master" * or Branch Ref - * @param {Function} callback * @return {Commit} */ Repository.prototype.getReferenceCommit = function(name, callback) { @@ -80,9 +81,9 @@ Repository.prototype.getReferenceCommit = function(name, callback) { /** * Look up a branch. Alias for `getReference` * +* @async * @param {String|Ref} name Ref name, e.g. "master", "refs/heads/master" * or Branch Ref -* @param {Function} callback * @return {Ref} */ Repository.prototype.getBranch = function(name, callback) { @@ -92,9 +93,9 @@ Repository.prototype.getBranch = function(name, callback) { /** * Look up a branch's most recent commit. Alias to `getReferenceCommit` * +* @async * @param {String|Ref} name Ref name, e.g. "master", "refs/heads/master" * or Branch Ref -* @param {Function} callback * @return {Commit} */ Repository.prototype.getBranchCommit = function(name, callback) { @@ -104,6 +105,7 @@ Repository.prototype.getBranchCommit = function(name, callback) { /** * Gets the branch that HEAD currently points to * Is an alias to head() + * @async * @return {Reference} */ Repository.prototype.getCurrentBranch = function() { @@ -113,9 +115,9 @@ Repository.prototype.getCurrentBranch = function() { /** * Lookup the reference with the given name. * + * @async * @param {String|Ref} name Ref name, e.g. "master", "refs/heads/master" * or Branch Ref - * @param {Function} callback * @return {Reference} */ Repository.prototype.getReference = function(name, callback) { @@ -180,10 +182,25 @@ Repository.getReferences = function(repo, type, refNamesOnly, callback) { }); }; + +/** + * Lookup references for a repository. + * + * @async + * @param {Reference.TYPE} type Type of reference to look up + * @return {Array} + */ Repository.prototype.getReferences = function(type, callback) { return Repository.getReferences(this, type, false, callback); }; +/** + * Lookup reference names for a repository. + * + * @async + * @param {Reference.TYPE} type Type of reference to look up + * @return {Array} + */ Repository.prototype.getReferenceNames = function(type, callback) { return Repository.getReferences(this, type, true, callback); }; @@ -191,8 +208,8 @@ Repository.prototype.getReferenceNames = function(type, callback) { /** * Retrieve the commit identified by oid. * + * @async * @param {String|Oid} String sha or Oid - * @param {Function} callback * @return {Commit} */ Repository.prototype.getCommit = function(oid, callback) { @@ -212,8 +229,8 @@ Repository.prototype.getCommit = function(oid, callback) { /** * Retrieve the blob represented by the oid. * + * @async * @param {String|Oid} String sha or Oid - * @param {Function} callback * @return {Blob} */ Repository.prototype.getBlob = function(oid, callback) { @@ -233,8 +250,8 @@ Repository.prototype.getBlob = function(oid, callback) { /** * Retrieve the tree represented by the oid. * + * @async * @param {String|Oid} String sha or Oid - * @param {Function} callback * @return {Tree} */ Repository.prototype.getTree = function(oid, callback) { @@ -254,8 +271,8 @@ Repository.prototype.getTree = function(oid, callback) { /** * Retrieve the tag represented by the oid. * + * @async * @param {String|Oid} String sha or Oid - * @param {Function} callback * @return {Tag} */ Repository.prototype.getTag = function(oid, callback) { @@ -275,8 +292,8 @@ Repository.prototype.getTag = function(oid, callback) { /** * Retrieve the tag represented by the tag name. * + * @async * @param {String} Short or full tag name - * @param {Function} callback * @return {Tag} */ Repository.prototype.getTagByName = function(name, callback) { @@ -302,7 +319,6 @@ Repository.prototype.getTagByName = function(name, callback) { * See also `Commit.prototype.history()` * * @param {String|Oid} String sha or Oid - * @param {Function} callback * @return {RevWalk} */ Repository.prototype.createRevWalk = function() { @@ -314,7 +330,7 @@ Repository.prototype.createRevWalk = function() { /** * Retrieve the master branch commit. * - * @param {Function} callback + * @async * @return {Commit} */ Repository.prototype.getMasterCommit = function(callback) { @@ -324,7 +340,7 @@ Repository.prototype.getMasterCommit = function(callback) { /** * Retrieve the commit that HEAD is currently pointing to * - * @param {Function} callback + * @async * @return {Commit} */ Repository.prototype.getHeadCommit = function(callback) { @@ -338,13 +354,13 @@ Repository.prototype.getHeadCommit = function(callback) { /** * Create a commit * + * @async * @param {String} updateRef * @param {Signature} author * @param {Signature} committer * @param {String} message * @param {Tree|Oid|String} Tree * @param {Array} parents - * @param {Function} callback * @return {Oid} The oid of the commit */ Repository.prototype.createCommit = function( @@ -394,11 +410,11 @@ Repository.prototype.createCommit = function( /** * Creates a new commit on HEAD from the list of passed in files + * @async * @param {Array} filesToAdd * @param {Signature} author * @param {Signature} committer * @param {String} message - * @param {Function} callback * @return {Oid} The oid of the new commit */ Repository.prototype.createCommitOnHead = function( @@ -438,7 +454,6 @@ Repository.prototype.createCommitOnHead = function( * Create a blob from a buffer * * @param {Buffer} buffer - * @param {Function} callback * @return {Blob} */ Repository.prototype.createBlobFromBuffer = function(buffer, callback) { diff --git a/lib/revwalk.js b/lib/revwalk.js index a59df077e..638596b34 100644 --- a/lib/revwalk.js +++ b/lib/revwalk.js @@ -61,7 +61,7 @@ Revwalk.prototype.walk = function(oid, callback) { * Walk the history grabbing commits until the checkFn called with the * current commit returns false. * - * @param {Function} checkFn + * @param {Function} checkFn function returns false to stop walking * @return {Array} */ Revwalk.prototype.getCommitsUntil = function(checkFn) { @@ -87,10 +87,10 @@ Revwalk.prototype.getCommitsUntil = function(checkFn) { }; /** - * Get some of commits. + * Get a number of commits. * * @param {Number} count (default: 10) - * @return {Array} + * @return {Array} */ Revwalk.prototype.getCommits = function(count) { count = count || 10; diff --git a/lib/tag.js b/lib/tag.js index 2a6c51f90..bffdf4677 100644 --- a/lib/tag.js +++ b/lib/tag.js @@ -5,9 +5,9 @@ var Tag = git.Tag; /** * Retrieves the tag pointed to by the oid +* @async * @param {Repository} repo The repo that the tag lives in * @param {String|Oid|Tag} id The tag to lookup -* @param {Function} callback * @return {Tag} */ Tag.lookup = LookupWrapper(Tag); diff --git a/lib/tree.js b/lib/tree.js index ca35af90a..2b131f98d 100644 --- a/lib/tree.js +++ b/lib/tree.js @@ -7,6 +7,7 @@ var LookupWrapper = require("./util/lookupWrapper"); /** * Retrieves the tree pointed to by the oid +* @async * @param {Repository} repo The repo that the tree lives in * @param {String|Oid|Tree} id The tree to lookup * @param {Function} callback @@ -16,6 +17,7 @@ Tree.lookup = LookupWrapper(Tree); /** * Diff two trees + * @async * @param {Tree} tree to diff against * @param {Function} callback * @return {DiffList} @@ -94,8 +96,9 @@ Tree.prototype.entries = function() { * Recursively walk the tree in breadth-first order. Fires an event for each * entry. * - * @fires Tree#entry - * @fires Tree#end + * @fires EventEmitter#entry Tree + * @fires EventEmitter#end Array + * @fires EventEmitter#error Error * * @param {Boolean} [blobsOnly = true] True to emit only blob & blob executable * entries. diff --git a/lib/tree_entry.js b/lib/tree_entry.js index 9d145a866..672c9bc33 100644 --- a/lib/tree_entry.js +++ b/lib/tree_entry.js @@ -43,6 +43,7 @@ TreeEntry.prototype.sha = function() { /** * Retrieve the tree for this entry. Make sure to call `isTree` first! + * @async * @return {Tree} */ TreeEntry.prototype.getTree = function(callback) { @@ -61,6 +62,7 @@ TreeEntry.prototype.getTree = function(callback) { /** * Retrieve the tree for this entry. Make sure to call `isTree` first! + * @async * @return {Blob} */ TreeEntry.prototype.getBlob = function(callback) {