Comments for text editor functions. More to come tomorrow.

source/blender/src/drawtext.c

@@ -136,7 +136,6 @@ static int check_identifier(char ch);
 static int check_whitespace(char ch);
 
 static int get_wrap_width(SpaceText *st);
-//static int get_wrap_points(SpaceText *st, char *line);
 static void get_suggest_prefix(Text *text, int offset);
 static void confirm_suggestion(Text *text, int skipleft);
 
@@ -238,6 +237,13 @@ static int render_string (SpaceText *st, char *in)
 	return r;
 }
 
+/* Checks the specified source string for a Python built-in function name. This
+ name must start at the beginning of the source string and must be followed by
+ a non-identifier (see check_identifier(char)) or null character.
+ 
+ If a built-in function is found, the length of the matching name is returned.
+ Otherwise, -1 is returned.
+ */
 static int find_builtinfunc(char *string)
 {
 	int a, i;
@@ -249,53 +255,50 @@ static int find_builtinfunc(char *string)
 	for (a=0; a<30; a++) {
 		i = 0;
 		while (1) {
+			/* If we hit the end of a keyword... (eg. "def") */
 			if (builtinfuncs[a][i]=='\0') {
+				/* If we still have identifier chars in the source (eg. "definate") */
 				if (check_identifier(string[i]))
-					i = -1;
+					i = -1; /* No match */
-				break;
+				break; /* Next keyword if no match, otherwise we're done */
+				
+			/* If chars mismatch, move on to next keyword */
 			} else if (string[i]!=builtinfuncs[a][i]) {
 				i = -1;
-				break;
+				break; /* Break inner loop, start next keyword */
 			}
 			i++;
 		}
-		if (i>0) break;
+		if (i>0) break; /* If we have a match, we're done */
 	}
 	return i;
 }
 
+/* Checks the specified source string for a Python special name. This name must
+ start at the beginning of the source string and must be followed by a non-
+ identifier (see check_identifier(char)) or null character.
+ 
+ If a special name is found, the length of the matching name is returned.
+ Otherwise, -1 is returned.
+ */
 static int find_specialvar(char *string) 
 {
 	int i = 0;
-	
+	/* Check for "def" */
 	if (string[0]=='d' && string[1]=='e' && string[2]=='f')
 		i = 3;
+	/* Check for "class" */
 	else if (string[0]=='c' && string[1]=='l' && string[2]=='a' && string[3]=='s' && string[4]=='s')
 		i = 5;
+	/* If next source char is an identifier (eg. 'i' in "definate") no match */
 	if (i==0 || check_identifier(string[i]))
 		return -1;
 	return i;
 }
 
-#if 0 // not used 
+/* Ensures the format string for the given line is long enough, reallocating
-static void print_format(SpaceText *st, TextLine *line) {
+ as needed. Allocation is done here, alone, to ensure consitency.
-	int i, a;
+ */
-	char *s, *f;
-	
-	s = line->line;
-	f = line->format;
-	for (a=0; *s; s++) {
-		if (*s == '\t') {
-			for (i=st->tabnumber-(a%st->tabnumber); i>0; i--)
-				printf(" "), f++, a++;
-		} else
-			printf("%c", *s), f++, a++;
-	}
-	printf("\n%s [%#x]\n", line->format, (int) (f[strlen(f)+1]));
-}
-#endif // not used
-
-/* Ensures the format string for the given line is long enough, reallocating as needed */
 static int check_format_len(TextLine *line, unsigned int len)
 {
 	if (line->format) {
@@ -311,18 +314,19 @@ static int check_format_len(TextLine *line, unsigned int len)
 	return 1;
 }
 
-/* Formats the specified line and if allowed and needed will move on to the
+/* Formats the specified line. If do_next is set, the process will move on to
- * next line. The format string contains the following characters:
+ the succeeding line if it is affected (eg. multiline strings). Format strings
- *		'_'		Whitespace
+ may contain any of the following characters:
- *		'#'		Comment text
+ 	'_'		Whitespace
- *		'!'		Punctuation and other symbols
+ 	'#'		Comment text
- *		'n'		Numerals
+ 	'!'		Punctuation and other symbols
- *		'l'		String letters
+ 	'n'		Numerals
- *		'v'		Special variables (class, def)
+ 	'l'		String letters
- *		'b'		Built-in names (print, for, etc.)
+ 	'v'		Special variables (class, def)
- *		'q'		Other text (identifiers, etc.)
+ 	'b'		Built-in names (print, for, etc.)
- * It is terminated with a null-terminator '\0' followed by a continuation
+ 	'q'		Other text (identifiers, etc.)
- * flag indicating whether the line is part of a multi-line string.
+ It is terminated with a null-terminator '\0' followed by a continuation
+ flag indicating whether the line is part of a multi-line string.
  */
 void txt_format_line(SpaceText *st, TextLine *line, int do_next)
 {
@@ -435,6 +439,7 @@ void txt_format_line(SpaceText *st, TextLine *line, int do_next)
 	}
 }
 
+/* Formats every line of the current text */
 void txt_format_text(SpaceText *st) 
 {
 	TextLine *linep;
@@ -445,6 +450,7 @@ void txt_format_text(SpaceText *st)
 		txt_format_line(st, linep, 0);
 }
 
+/* Sets the current drawing color based on the format character specified */
 static void format_draw_color(char formatchar)
 {
 	switch (formatchar) {
@@ -691,33 +697,6 @@ static int get_wrap_width(SpaceText *st)
 	return max>8 ? max : 8;
 }
 
-#if 0 // not used 
-/* Returns the number of wrap points (or additional lines) in the given string */
-static int get_wrap_points(SpaceText *st, char *line) 
-{
-	int start, end, taboffs, i, max, count;
-	
-	if (!st->wordwrap) return 0;
-
-	end= max= get_wrap_width(st);
-	count= taboffs= start= 0;
-
-	for (i=0; line[i]!='\0'; i++) {
-		if (i-start+taboffs>=max) {
-			count++;
-			start= end;
-			end += max;
-			taboffs= 0;
-		} else if (line[i]==' ' || line[i]=='\t' || line[i]=='-') {
-			end = i+1;
-			if (line[i]=='\t')
-				taboffs += st->tabnumber-(i-start)%st->tabnumber;
-		}
-	}
-	return count;
-}
-#endif // not used
-
 /* Sets (offl, offc) for transforming (line, curs) to its wrapped position */
 static void wrap_offset(SpaceText *st, TextLine *linein, int cursin, int *offl, int *offc)
 {
@@ -1063,6 +1042,7 @@ static void draw_textscroll(SpaceText *st)
 	uiEmboss(st->txtbar.xmin, st->txtbar.ymin, st->txtbar.xmax, st->txtbar.ymax, st->flags & ST_SCROLL_SELECT);
 }
 
+/* Moves the view vertically by the specified number of lines */
 static void screen_skip(SpaceText *st, int lines)
 {
 	int last;
@@ -1080,6 +1060,12 @@ static void screen_skip(SpaceText *st, int lines)
 	if (st->top<0) st->top= 0;
 }
 
+/* Moves the cursor vertically by the specified number of lines.
+ If the destination line is shorter than the current cursor position, the
+ cursor will be positioned at the end of this line.
+
+ This is to replace screen_skip for PageUp/Down operations.
+ */
 static void cursor_skip(SpaceText *st, int lines, int sel)
 {
 	Text *text;
@@ -1112,9 +1098,8 @@ static void cursor_skip(SpaceText *st, int lines, int sel)
 	txt_undo_add_toop(st->text, sel?UNDO_STO:UNDO_CTO, oldl, oldc, txt_get_span(text->lines.first, *linep), *charp);
 }
 
-/* 
+/* Handles text scrolling via grabbing the view (MMB, mode 1) or with the
- * mode 1 == view scroll
+ scrollbar (mode 2)
- * mode 2 == scrollbar
  */
 static void do_textscroll(SpaceText *st, int mode)
 {
@@ -1483,10 +1468,12 @@ static short check_blockhandler(SpaceText *st, short handler)
 	return 0;
 }
 
+/* Find and replace GUI panel */
 static void text_panel_find(short cntrl)	// TEXT_HANDLER_FIND
 {
 	uiBlock *block;
 
+	/* Ensure that find and replace buffers have been allocated */
 	if (!g_find_str || !g_replace_str) {
 		g_find_str= MEM_mallocN(TXT_MAXFINDSTR+1, "find_string");
 		g_replace_str= MEM_mallocN(TXT_MAXFINDSTR+1, "replace_string");