Skip to content

Commit 4c48b11

Browse files
facelegfaceleg
committed
Updated commit documentation
1 parent bf568bd commit 4c48b11

File tree

1 file changed

+89
-20
lines changed

1 file changed

+89
-20
lines changed

‎lib/commit.js‎

Lines changed: 89 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@ var git = require( '../' ),
66
* Convenience commit constructor.
77
*
88
* @constructor
9-
* @param {RawCommit|Null} rawCommit
10-
* @return {Commit}
9+
* @param {git.raw.Repo} rawRepo Raw repository object.
10+
* @param {git.raw.Commit} [rawCommit = new git.raw.Commit(rawRepo)] Raw commit object.
1111
*/
1212
var Commit = function(rawRepo, rawCommit) {
1313
if (!(rawRepo instanceof git.raw.Repo)) {
@@ -26,10 +26,15 @@ var Commit = function(rawRepo, rawCommit) {
2626
/**
2727
* Look up the commit referenced by oid, replace this.commit with the result.
2828
*
29-
* @param {git.oid|git.raw.Oid|String} oid
30-
* @param {Function} callback
29+
* @param {Oid|git.raw.Oid|String} oid A representation of an OID used to lookup the commit.
30+
* @param {Commit~lookupCallback} callback
3131
*/
3232
Commit.prototype.lookup = function(oid, callback) {
33+
/**
34+
* @callback Commit~lookupCallback Callback executed on lookup completion.
35+
* @param {GitError|null} error An Error or null if successful.
36+
* @param {Commit|null} commit Retrieved commit object or null.
37+
*/
3338
if (typeof oid !== 'undefined' &&
3439
typeof oid !== 'string' &&
3540
!(oid instanceof git.raw.Oid)) {
@@ -45,20 +50,30 @@ Commit.prototype.lookup = function(oid, callback) {
4550
};
4651

4752
/**
48-
* Retrieve the commit's Oid
53+
* Retrieve the commit's OID.
4954
*
50-
* @param {Function} callback
55+
* @param {Commit~oidCallback} callback
5156
*/
5257
Commit.prototype.oid = function(callback) {
58+
/**
59+
* @callback Commit~oidCallback Callback executed on OID retrieval.
60+
* @param {GitError|null} error An Error or null if successful.
61+
* @param {Oid|null} commit Retrieved OID object or null.
62+
*/
5363
callback(null, new git.oid(this.rawCommit.oid()));
5464
};
5565

5666
/**
57-
* Retrieve the SHA
67+
* Retrieve the SHA.
5868
*
59-
* @param {Function} callback
69+
* @param {Commit~shaCallback} callback
6070
*/
6171
Commit.prototype.sha = function(callback) {
72+
/**
73+
* @callback Commit~shaCallback Callback executed on SHA retrieval.
74+
* @param {GitError|null} error An Error or null if successful.
75+
* @param {String|null} sha Retrieved SHA.
76+
*/
6277
this.rawCommit.sha(function(error, sha) {
6378
if (success(error, callback)) {
6479
callback(null, sha);
@@ -69,9 +84,14 @@ Commit.prototype.sha = function(callback) {
6984
/**
7085
* Retrieve the message
7186
*
72-
* @param {Function} callback
87+
* @param {Commit~messageCallback} callback
7388
*/
7489
Commit.prototype.message = function(callback) {
90+
/**
91+
* @callback Commit~messageCallback Callback executed on message retrieval.
92+
* @param {GitError|null} error An Error or null if successful.
93+
* @param {String|null} message Retrieved message.
94+
*/
7595
this.rawCommit.message(function(error, message) {
7696
if (success(error, callback)) {
7797
callback(null, message);
@@ -80,11 +100,16 @@ Commit.prototype.message = function(callback) {
80100
};
81101

82102
/**
83-
* Retrieve the commit unix timestamp.
103+
* Retrieve the commit time as a unix timestamp in seconds.
84104
*
85-
* @param {Function} callback
105+
* @param {Commit~timeCallback} callback
86106
*/
87107
Commit.prototype.time = function(callback) {
108+
/**
109+
* @callback Commit~timeCallback Callback executed on time retrieval.
110+
* @param {GitError|null} error An Error or null if successful.
111+
* @param {Integer|null} time Retrieved time in seconds.
112+
*/
88113
this.rawCommit.time(function(error, time) {
89114
if (success(error, callback)) {
90115
callback(null, time);
@@ -95,9 +120,14 @@ Commit.prototype.time = function(callback) {
95120
/**
96121
* Retrieve the commit's positive or negative timezone offset, in minutes from UTC.
97122
*
98-
* @param {Function} callback
123+
* @param {Commit~offsetCallback} callback
99124
*/
100125
Commit.prototype.offset = function(callback) {
126+
/**
127+
* @callback Commit~offsetCallback Callback executed on offset retrieval.
128+
* @param {GitError|null} error An Error or null if successful.
129+
* @param {Integer|null} offset Retrieved offset in in minutes from UTC.
130+
*/
101131
this.rawCommit.offset(function(error, offset) {
102132
if (success(error, callback)) {
103133
callback(null, offset);
@@ -106,11 +136,16 @@ Commit.prototype.offset = function(callback) {
106136
};
107137

108138
/**
109-
* Retrieve the commit's author.
139+
* Retrieve the commit's author signature.
110140
*
111-
* @param {Function} callback
141+
* @param {Commit~authorCallback} callback
112142
*/
113143
Commit.prototype.author = function(callback) {
144+
/**
145+
* @callback Commit~authorCallback Callback executed on author retrieval.
146+
* @param {GitError|null} error An Error or null if successful.
147+
* @param {Signature|null} author Retrieved author signature.
148+
*/
114149
this.rawCommit.author(function(error, rawSignature) {
115150
if (success(error, callback)) {
116151
callback(null, new git.signature(rawSignature));
@@ -121,9 +156,14 @@ Commit.prototype.author = function(callback) {
121156
/**
122157
* Retrieve the commit's committer.
123158
*
124-
* @param {Function} callback
159+
* @param {Commit~committerCalback} callback
125160
*/
126161
Commit.prototype.committer = function(callback) {
162+
/**
163+
* @callback Commit~committerCallback Callback executed on committer retrieval.
164+
* @param {GitError|null} error An Error or null if successful.
165+
* @param {Signature|null} committer Retrieved committer signature.
166+
*/
127167
this.rawCommit.committer(function(error, rawSignature) {
128168
if (success(error, callback)) {
129169
callback(null, new git.signature(rawSignature));
@@ -134,9 +174,14 @@ Commit.prototype.committer = function(callback) {
134174
/**
135175
* Retrieve the tree for this commit.
136176
*
137-
* @param {Function} callback
177+
* @param {Commit~treeCallback} callback
138178
*/
139179
Commit.prototype.tree = function(callback) {
180+
/**
181+
* @callback Commit~treeCallback Callback executed on tree retrieval.
182+
* @param {GitError|null} error An Error or null if successful.
183+
* @param {Tree|null} tree Retrieved tree.
184+
*/
140185
var self = this;
141186
self.rawCommit.tree(function commitTree(error, rawTree) {
142187
if (success(error, callback)) {
@@ -147,11 +192,17 @@ Commit.prototype.tree = function(callback) {
147192

148193
/**
149194
* Retrieve the file represented by path for this commit.
195+
* Path must be relative to repository root.
150196
*
151-
* @param {String} path
152-
* @param {Function} callback
197+
* @param {String} path
198+
* @param {Commit~fileCallback} callback
153199
*/
154200
Commit.prototype.file = function(path, callback) {
201+
/**
202+
* @callback Commit~fileCallback Callback executed on file retrieval.
203+
* @param {GitError|null} error An Error or null if successful.
204+
* @param {Entry|null} file Retrieved file entry.
205+
*/
155206
this.tree(function commitFile(error, tree) {
156207
if (!success(error, callback)) {
157208
return;
@@ -167,8 +218,10 @@ Commit.prototype.file = function(path, callback) {
167218
/**
168219
* Walk the history of this commit.
169220
*
170-
* @return {Event} Event emits 'commit', with error, commit and 'end', with
171-
* error, commits[]
221+
* @fires Commit#commit
222+
* @fires Commit#end
223+
*
224+
* @return {EventEmitter} Event
172225
*/
173226
Commit.prototype.history = function() {
174227
var event = new events.EventEmitter(),
@@ -184,9 +237,25 @@ Commit.prototype.history = function() {
184237
}
185238

186239
if (noMoreCommits) {
240+
/**
241+
* End event.
242+
*
243+
* @event Commit#end
244+
*
245+
* @param {GitError|null} error An error object if there was an issue, null otherwise.
246+
* @param {Commit[]} commits The commits.
247+
*/
187248
event.emit('end', null, commits);
188249
return;
189250
}
251+
/**
252+
* Commit event.
253+
*
254+
* @event Commit#commit
255+
*
256+
* @param {GitError|null} error An error object if there was an issue, null otherwise.
257+
* @param {Commit} commit The commit.
258+
*/
190259
event.emit('commit', null, commit);
191260
commits.push(commit);
192261
});

0 commit comments

Comments
 (0)