Skip to content

Commit ecf03e4

Browse files
nkallennkallen
committed
Better documentation
1 parent 7f9f3c4 commit ecf03e4

File tree

16 files changed

+223
-97
lines changed

16 files changed

+223
-97
lines changed

‎lib/blob.js‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@ var git = require('../'),
22
TreeEntry = git.TreeEntry,
33
Blob = git.Blob;
44

5+
var oldContent = Blob.prototype.content;
6+
57
/**
6-
* Replace old content method with something nicer.
8+
* Retrieve the content of the blob.
9+
* @return {Buffer} content
710
*/
8-
var oldContent = Blob.prototype.content;
911
Blob.prototype.content = function() {
1012
return oldContent.call(this).toBuffer(this.size());
1113
};

‎lib/commit.js‎

Lines changed: 18 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,31 @@ var git = require('../'),
44

55
/**
66
* Retrieve the SHA.
7+
* @return {String}
78
*/
89
Commit.prototype.sha = function() {
910
return this.oid().sha();
1011
};
1112

1213
/**
1314
* Retrieve the commit time as a unix timestamp.
15+
* @return {Number}
1416
*/
1517
Commit.prototype.timeMs = function() {
1618
return this.time() * 1000;
1719
};
1820

1921
/**
2022
* Retrieve the commit time as a Date object.
23+
* @return {Date}
2124
*/
2225
Commit.prototype.date = function() {
2326
return new Date(this.timeMs());
2427
};
2528

2629
/**
2730
* Get the tree associated with this commit.
31+
* @return {Tree}
2832
*/
2933
Commit.prototype.getTree = function(callback) {
3034
this.repo.getTree(this.treeId(), callback);
@@ -35,14 +39,10 @@ Commit.prototype.getTree = function(callback) {
3539
* Path must be relative to repository root.
3640
*
3741
* @param {String} path
38-
* @param {Commit~fileCallback} callback
42+
* @param {Function} callback
43+
* @return {TreeEntry}
3944
*/
4045
Commit.prototype.getEntry = function(path, callback) {
41-
/**
42-
* @callback Commit~fileCallback Callback executed on file retrieval.
43-
* @param {GitError|null} error An Error or null if successful.
44-
* @param {Entry|null} file Retrieved file entry.
45-
*/
4646
this.getTree(function(error, tree) {
4747
if (error) return callback(error);
4848

@@ -54,11 +54,12 @@ Commit.prototype.getEntry = function(path, callback) {
5454
* Walk the history from this commit backwards.
5555
* An EventEmitter is returned that will emit a 'commit' event for each
5656
* commit in the history, and one 'end' event when the walk is completed.
57+
* Don't forget to call `start()` on the returned event.
5758
*
5859
* @fires Commit#commit
5960
* @fires Commit#end
6061
*
61-
* @return {EventEmitter} historyWalkEmitter
62+
* @return {EventEmitter}
6263
*/
6364
Commit.prototype.history = function() {
6465
var event = new events.EventEmitter();
@@ -71,25 +72,9 @@ Commit.prototype.history = function() {
7172
if (error) return event.emit('error', error);
7273

7374
if (!commit) {
74-
/**
75-
* End event.
76-
*
77-
* @event Commit#end
78-
*
79-
* @param {GitError|null} error An error object if there was an issue, null otherwise.
80-
* @param {Commit[]} commits The commits.
81-
*/
8275
event.emit('end', commits);
8376
return;
8477
}
85-
/**
86-
* Commit event.
87-
*
88-
* @event Commit#commit
89-
*
90-
* @param {GitError|null} error An error object if there was an issue, null otherwise.
91-
* @param {Commit} commit The commit.
92-
*/
9378
event.emit('commit', commit);
9479
commits.push(commit);
9580
});
@@ -100,14 +85,10 @@ Commit.prototype.history = function() {
10085
/**
10186
* Retrieve the commit's parents -- as commit objects.
10287
*
103-
* @param {Commit~parentsCallback} callback
88+
* @param {Function} callback
89+
* @return {[Commit]} array of commits
10490
*/
10591
Commit.prototype.getParents = function(callback) {
106-
/**
107-
* @callback Commit~parentsCallback Callback executed on parents retrieval.
108-
* @param {GitError|null} error An Error or null if successful.
109-
* @param {Commit[]|null} parents Commit's parent(s).
110-
*/
11192
var self = this;
11293
function processParents(commit, n, acc, callback) {
11394
if (n < 0) return callback(null, acc);
@@ -124,7 +105,8 @@ Commit.prototype.getParents = function(callback) {
124105
/**
125106
* Retrieve the commit's parent shas.
126107
*
127-
* @param {Commit~parentsCallback} callback
108+
* @param {Function} callback
109+
* @return {[Oid]} array of oids
128110
*/
129111
Commit.prototype.parents = function() {
130112
var result = [];
@@ -138,14 +120,10 @@ Commit.prototype.parents = function() {
138120
* Generate an array of diff trees showing changes between this commit
139121
* and its parent(s).
140122
*
141-
* @param {Commit~parentsDiffTreesCallback} callback
123+
* @param {Function} callback
124+
* @return {[DiffList]} an array of difflists
142125
*/
143126
Commit.prototype.getDiff = function(callback) {
144-
/**
145-
* @callback Commit~parentsDiffTreesCallback Callback executed on diff trees retrieval.
146-
* @param {GitError|null} error An Error or null if successful.
147-
* @param {DiffList[]|null} diffLists Array of DiffTrees showing changes between this commit and its parent(s)
148-
*/
149127
var self = this;
150128
self.getParents(function commitParents(error, parents) {
151129
if (error) return callback(error);
@@ -172,6 +150,10 @@ Commit.prototype.getDiff = function(callback) {
172150
});
173151
};
174152

153+
/**
154+
* The sha of this commit
155+
* @return {String}
156+
*/
175157
Commit.prototype.toString = function() {
176158
return this.sha();
177159
};

‎lib/convenient_hunk.js‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,27 @@ function ConvenientHunk(raw, i) {
33
this.i = i;
44
}
55

6+
/**
7+
* Diff header string that represents the context of this hunk
8+
* of the diff. Something like `@@ -169,14 +167,12 @@ ...`
9+
* @return {String}
10+
*/
611
ConvenientHunk.prototype.header = function() {
712
return this.raw.hunk(this.i).header;
813
};
914

15+
/**
16+
* Number of lines in this hunk
17+
* @return {Number}
18+
*/
1019
ConvenientHunk.prototype.size = function() {
1120
return this.raw.hunk(this.i).lines;
1221
};
1322

23+
/**
24+
* The lines in this hunk
25+
* @return {[String]} array of strings
26+
*/
1427
ConvenientHunk.prototype.lines = function() {
1528
var result = [];
1629
for (var i = 0; i < this.size(); i++)

‎lib/convenient_patch.js‎

Lines changed: 63 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,63 +6,119 @@ function ConvenientPatch(raw) {
66
this.raw = raw;
77
}
88

9+
/**
10+
* Old name of the file
11+
* @return {String}
12+
*/
913
ConvenientPatch.prototype.oldFile = function() {
1014
return this.raw.delta.oldFile();
1115
};
1216

17+
/**
18+
* New name of the file
19+
* @return {String}
20+
*/
1321
ConvenientPatch.prototype.newFile = function() {
1422
return this.raw.delta.newFile();
1523
};
1624

25+
/**
26+
* The number of hunks in this patch
27+
* @return {Number}
28+
*/
1729
ConvenientPatch.prototype.size = function() {
1830
return this.raw.patch.size();
1931
};
2032

33+
/**
34+
* The hunks in this patch
35+
* @return {[ConvenientHunk]} an array of ConvenientHunks
36+
*/
37+
ConvenientPatch.prototype.hunks = function() {
38+
var result = [];
39+
for (var i = 0; i < this.size(); i++)
40+
result.push(new ConvenientHunk(this.raw.patch, i));
41+
return result;
42+
};
43+
44+
/**
45+
* The status of this patch (unmodified, added, deleted)
46+
* @return {Number}
47+
*/
2148
ConvenientPatch.prototype.status = function() {
2249
return this.raw.delta.status();
2350
};
2451

52+
/**
53+
* Is this an unmodified patch?
54+
* @return {Boolean}
55+
*/
2556
ConvenientPatch.prototype.isUnmodified = function() {
2657
return this.status() == DiffList.Delta.Unmodified;
2758
};
2859

60+
/**
61+
* Is this an added patch?
62+
* @return {Boolean}
63+
*/
2964
ConvenientPatch.prototype.isAdded = function() {
3065
return this.status() == DiffList.Delta.Added;
3166
};
3267

68+
/**
69+
* Is this a deleted patch?
70+
* @return {Boolean}
71+
*/
3372
ConvenientPatch.prototype.isDeleted = function() {
3473
return this.status() == DiffList.Delta.Deleted;
3574
};
3675

76+
/**
77+
* Is this an modified patch?
78+
* @return {Boolean}
79+
*/
3780
ConvenientPatch.prototype.isModified = function() {
3881
return this.status() == DiffList.Delta.Modified;
3982
};
4083

84+
/**
85+
* Is this a renamed patch?
86+
* @return {Boolean}
87+
*/
4188
ConvenientPatch.prototype.isRenamed = function() {
4289
return this.status() == DiffList.Delta.Renamed;
4390
};
4491

92+
/**
93+
* Is this a copied patch?
94+
* @return {Boolean}
95+
*/
4596
ConvenientPatch.prototype.isCopied = function() {
4697
return this.status() == DiffList.Delta.Copied;
4798
};
4899

100+
/**
101+
* Is this an ignored patch?
102+
* @return {Boolean}
103+
*/
49104
ConvenientPatch.prototype.isIgnored = function() {
50105
return this.status() == DiffList.Delta.Ignored;
51106
};
52107

108+
/**
109+
* Is this an untracked patch?
110+
* @return {Boolean}
111+
*/
53112
ConvenientPatch.prototype.isUntracked = function() {
54113
return this.status() == DiffList.Delta.Untracked;
55114
};
56115

116+
/**
117+
* Is this a type change?
118+
* @return {Boolean}
119+
*/
57120
ConvenientPatch.prototype.isTypeChange = function() {
58121
return this.status() == DiffList.Delta.TypeChange;
59122
};
60123

61-
ConvenientPatch.prototype.hunks = function() {
62-
var result = [];
63-
for (var i = 0; i < this.size(); i++)
64-
result.push(new ConvenientHunk(this.raw.patch, i));
65-
return result;
66-
};
67-
68124
exports.ConvenientPatch = ConvenientPatch;

‎lib/diff_list.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,9 @@ DiffList.LineOrigin = {
3939
};
4040

4141
/**
42-
* Retrieve patches
42+
* Retrieve patches in this difflist
4343
*
44-
* @return {Array} patches
44+
* @return {[ConvenientPatch]} an array of ConvenientPatches
4545
*/
4646
DiffList.prototype.patches = function() {
4747
var size = this.size();

‎lib/index.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ var git = require('../'),
33

44
/**
55
* Return an array of the entries in this index.
6+
* @return {[IndexEntry]} an array of IndexEntrys
67
*/
78
Index.prototype.entries = function() {
89
var size = this.size(),

‎lib/object.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,34 @@ git.Object.Type = {
1313
OidDelta: 7 /**< A delta, base is given by object id. */
1414
};
1515

16+
/**
17+
* Is this object a commit?
18+
* @return {Boolean}
19+
*/
1620
git.Object.prototype.isCommit = function() {
1721
return this.type() == Object.Type.Commit;
1822
};
1923

24+
/**
25+
* Is this object a tree?
26+
* @return {Boolean}
27+
*/
2028
git.Object.prototype.isTree = function() {
2129
return this.type() == Object.Type.Tree;
2230
};
2331

32+
/**
33+
* Is this object a blob?
34+
* @return {Boolean}
35+
*/
2436
git.Object.prototype.isBlob = function() {
2537
return this.type() == Object.Type.Blob;
2638
};
2739

40+
/**
41+
* Is this object a tag?
42+
* @return {Boolean}
43+
*/
2844
git.Object.prototype.isTag = function() {
2945
return this.type() == Object.Type.Tag;
3046
};

‎lib/odb.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@ var git = require('../'),
66
* Retrieve the object identified by oid.
77
*
88
* @param {String|Oid} String sha or Oid
9-
* @param {Repo~commitCallback} callback
9+
* @param {Function} callback
10+
* @return {git.Object} a git odb object
1011
*/
1112
util.normalizeOid(Odb.prototype, 'read');
1213
util.makeSafe(Odb.prototype, 'read');

‎lib/oid.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
var git = require('../'),
22
Oid = git.Oid;
33

4+
/**
5+
* The hex representation of the SHA
6+
* @return {String}
7+
*/
48
Oid.prototype.toString = function() {
59
return this.sha();
610
};

0 commit comments

Comments
 (0)