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>
This commit is contained in:
Jakub Narebski 2011-04-28 21:04:02 +02:00 коммит произвёл Junio C Hamano
Родитель 9a86dd5710
Коммит e2895de4d8
2 изменённых файлов: 19 добавлений и 15 удалений

Просмотреть файл

@ -7,7 +7,7 @@
* @license GPLv2 or later
*/
/* ============================================================ */
/*
* This code uses DOM methods instead of (nonstandard) innerHTML
* to modify page.
@ -26,7 +26,7 @@
*/
/* ============================================================ */
/* ............................................................ */
/* utility/helper functions (and variables) */
var xhr; // XMLHttpRequest object
@ -132,7 +132,7 @@ function writeTimeInterval() {
}
/**
* show an error message alert to user within page (in prohress info area)
* show an error message alert to user within page (in progress info area)
* @param {String} str: plain text error message (no HTML)
*
* @globals div_progress_info
@ -182,7 +182,7 @@ function getColorNo(tr) {
var colorsFreq = [0, 0, 0];
/**
* return one of given possible colors (curently least used one)
* return one of given possible colors (currently least used one)
* example: chooseColorNoFrom(2, 3) returns 2 or 3
*
* @param {Number[]} arguments: one or more numbers
@ -203,8 +203,8 @@ function chooseColorNoFrom() {
}
/**
* given two neigbour <tr> elements, find color which would be different
* from color of both of neighbours; used to 3-color blame table
* given two neighbor <tr> elements, find color which would be different
* from color of both of neighbors; used to 3-color blame table
*
* @param {HTMLElement} tr_prev
* @param {HTMLElement} tr_next
@ -216,14 +216,14 @@ function findColorNo(tr_prev, tr_next) {
var color_next = getColorNo(tr_next);
// neither of neighbours has color set
// neither of neighbors has color set
// THEN we can use any of 3 possible colors
if (!color_prev && !color_next) {
return chooseColorNoFrom(1,2,3);
}
// either both neighbours have the same color,
// or only one of neighbours have color set
// either both neighbors have the same color,
// or only one of neighbors have color set
// THEN we can use any color except given
var color;
if (color_prev === color_next) {
@ -237,7 +237,7 @@ function findColorNo(tr_prev, tr_next) {
return chooseColorNoFrom((color % 3) + 1, ((color+1) % 3) + 1);
}
// neighbours have different colors
// neighbors have different colors
// THEN there is only one color left
return (3 - ((color_prev + color_next) % 3));
}
@ -258,7 +258,7 @@ function isStartOfGroup(tr) {
/**
* change colors to use zebra coloring (2 colors) instead of 3 colors
* concatenate neighbour commit groups belonging to the same commit
* concatenate neighbor commit groups belonging to the same commit
*
* @globals colorRe
*/

Просмотреть файл

@ -13,14 +13,17 @@
/* Padding */
/**
* pad number N with nonbreakable spaces on the left, to WIDTH characters
* pad INPUT on the left with STR that is assumed to have visible
* width of single character (for example nonbreakable spaces),
* to WIDTH characters
*
* example: padLeftStr(12, 3, '\u00A0') == '\u00A012'
* ('\u00A0' is nonbreakable space)
*
* @param {Number|String} input: number to pad
* @param {Number} width: visible width of output
* @param {String} str: string to prefix to string, e.g. '\u00A0'
* @returns {String} INPUT prefixed with (WIDTH - INPUT.length) x STR
* @returns {String} INPUT prefixed with STR x (WIDTH - INPUT.length)
*/
function padLeftStr(input, width, str) {
var prefix = '';
@ -34,7 +37,7 @@ function padLeftStr(input, width, str) {
}
/**
* Pad INPUT on the left to SIZE width, using given padding character CH,
* Pad INPUT on the left to WIDTH, using given padding character CH,
* for example padLeft('a', 3, '_') is '__a'.
*
* @param {String} input: input value converted to string.
@ -140,7 +143,8 @@ var maybeQuotedRe = /^\"(.*)\"$/;
/**#@-*/
/**
* unquote maybe git-quoted filename
* unquote maybe C-quoted filename (as used by git, i.e. it is
* in double quotes '"' if there is any escape character used)
* e.g. 'aa' -> 'aa', '"a\ta"' -> 'a a'
*
* @param {String} str: git-quoted string