gitweb.js: Update and improve comments in JavaScript files
This consists of adding a few extra explanation, fixing descriptions of functions to match names of parameters in code, adding a few separators, and fixing spelling -- while at it spell 'neighbor' using American spelling (and not as 'neighbour'). This is post-split cleanup. Signed-off-by: Jakub Narebski <jnareb@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jakub Narebski committed
Apr 28, 2011 at 21:04 UTC
e2895de4d8efef52e835731aaaaa9467e2110e62
2 files changed
+19
-15
gitweb/static/js/blame_incremental.js
+11
-11
@@ -7,7 +7,7 @@
7
* @license GPLv2 or later
8
*/
9
10
-
10
+/* ============================================================ */
11
/*
12
* This code uses DOM methods instead of (nonstandard) innerHTML
13
* to modify page.
@@ -26,7 +26,7 @@
26
*/
27
28
29
-/* ============================================================ */
29
+/* ............................................................ */
30
/* utility/helper functions (and variables) */
31
32
var xhr; // XMLHttpRequest object
@@ -132,7 +132,7 @@ function writeTimeInterval() {
132
}
133
134
/**
135
- * show an error message alert to user within page (in prohress info area)
135
+ * show an error message alert to user within page (in progress info area)
136
* @param {String} str: plain text error message (no HTML)
137
*
138
* @globals div_progress_info
@@ -182,7 +182,7 @@ function getColorNo(tr) {
182
183
var colorsFreq = [0, 0, 0];
184
/**
185
- * return one of given possible colors (curently least used one)
185
+ * return one of given possible colors (currently least used one)
186
* example: chooseColorNoFrom(2, 3) returns 2 or 3
187
*
188
* @param {Number[]} arguments: one or more numbers
@@ -203,8 +203,8 @@ function chooseColorNoFrom() {
203
}
204
205
/**
206
- * given two neigbour <tr> elements, find color which would be different
207
- * from color of both of neighbours; used to 3-color blame table
206
+ * given two neighbor <tr> elements, find color which would be different
207
+ * from color of both of neighbors; used to 3-color blame table
208
*
209
* @param {HTMLElement} tr_prev
210
* @param {HTMLElement} tr_next
@@ -216,14 +216,14 @@ function findColorNo(tr_prev, tr_next) {
216
var color_next = getColorNo(tr_next);
217
218
219
- // neither of neighbours has color set
219
+ // neither of neighbors has color set
220
// THEN we can use any of 3 possible colors
221
if (!color_prev && !color_next) {
222
return chooseColorNoFrom(1,2,3);
223
}
224
225
- // either both neighbours have the same color,
226
- // or only one of neighbours have color set
225
+ // either both neighbors have the same color,
226
+ // or only one of neighbors have color set
227
// THEN we can use any color except given
228
var color;
229
if (color_prev === color_next) {
@@ -237,7 +237,7 @@ function findColorNo(tr_prev, tr_next) {
237
return chooseColorNoFrom((color % 3) + 1, ((color+1) % 3) + 1);
238
}
239
240
- // neighbours have different colors
240
+ // neighbors have different colors
241
// THEN there is only one color left
242
return (3 - ((color_prev + color_next) % 3));
243
}
@@ -258,7 +258,7 @@ function isStartOfGroup(tr) {
258
259
/**
260
* change colors to use zebra coloring (2 colors) instead of 3 colors
261
- * concatenate neighbour commit groups belonging to the same commit
261
+ * concatenate neighbor commit groups belonging to the same commit
262
*
263
* @globals colorRe
264
*/
gitweb/static/js/lib/common-lib.js
+8
-4
@@ -13,14 +13,17 @@
13
/* Padding */
14
15
/**
16
- * pad number N with nonbreakable spaces on the left, to WIDTH characters
16
+ * pad INPUT on the left with STR that is assumed to have visible
17
+ * width of single character (for example nonbreakable spaces),
18
+ * to WIDTH characters
19
+ *
20
* example: padLeftStr(12, 3, '\u00A0') == '\u00A012'
21
* ('\u00A0' is nonbreakable space)
22
*
23
* @param {Number|String} input: number to pad
24
* @param {Number} width: visible width of output
25
* @param {String} str: string to prefix to string, e.g. '\u00A0'
23
- * @returns {String} INPUT prefixed with (WIDTH - INPUT.length) x STR
26
+ * @returns {String} INPUT prefixed with STR x (WIDTH - INPUT.length)
27
*/
28
function padLeftStr(input, width, str) {
29
var prefix = '';
@@ -34,7 +37,7 @@ function padLeftStr(input, width, str) {
37
}
38
39
/**
37
- * Pad INPUT on the left to SIZE width, using given padding character CH,
40
+ * Pad INPUT on the left to WIDTH, using given padding character CH,
41
* for example padLeft('a', 3, '_') is '__a'.
42
*
43
* @param {String} input: input value converted to string.
@@ -140,7 +143,8 @@ var maybeQuotedRe = /^\"(.*)\"$/;
143
/**#@-*/
144
145
/**
143
- * unquote maybe git-quoted filename
146
+ * unquote maybe C-quoted filename (as used by git, i.e. it is
147
+ * in double quotes '"' if there is any escape character used)
148
* e.g. 'aa' -> 'aa', '"a\ta"' -> 'a a'
149
*
150
* @param {String} str: git-quoted string