PERFORCE change 145599 for review

[Gabor Kovesdan]

http://perforce.freebsd.org/chv.cgi?CH=145599

Change 145599 by gabor at gabor_server on 2008/07/22 10:59:09

	- Add a significant amount of comments.

Affected files ...

.. //depot/projects/soc2008/gabor_textproc/grep/file.c#19 edit
.. //depot/projects/soc2008/gabor_textproc/grep/grep.c#69 edit
.. //depot/projects/soc2008/gabor_textproc/grep/util.c#64 edit

Differences ...

==== //depot/projects/soc2008/gabor_textproc/grep/file.c#19 (text+ko) ====

@@ -61,6 +61,10 @@
 
 #define iswbinary(ch)	(!iswspace((ch)) && iswcntrl((ch)))
 
+/*
+ * Returns a single character according to the file type.
+ * Returns -1 on failure.
+ */
 int
 grep_fgetc(struct file *f)
 {
@@ -82,6 +86,10 @@
 	return (-1);
 }
 
+/*
+ * Returns true if the file position is a EOF, returns false
+ * otherwise.
+ */
 int
 grep_feof(struct file *f)
 {
@@ -97,6 +105,14 @@
 	return (1);
 }
 
+/*
+ * At the first call, fills in an internal buffer and checks if the given
+ * file is a binary file and sets the binary flag accordingly.  Then returns
+ * a single line and sets len to the length of the returned line.
+ * At any other call returns a single line either from the internal buffer
+ * or from the file if the buffer is exhausted and sets len to the length
+ * of the line.
+ */
 char *
 grep_fgetln(struct file *f, size_t *len)
 {
@@ -149,6 +165,9 @@
 	return (lnbuf);
 }
 
+/*
+ * Opens the standard input for processing.
+ */
 struct file *
 grep_stdin_open(void)
 {
@@ -165,6 +184,9 @@
 	return (NULL);
 }
 
+/*
+ * Opens a normal, a gzipped or a bzip2 compressed file for processing.
+ */
 struct file *
 grep_open(char *path)
 {
@@ -193,6 +215,9 @@
 	return (NULL);
 }
 
+/*
+ * Closes a normal, a gzipped or a bzip2 compressed file.
+ */
 void
 grep_close(struct file *f)
 {

==== //depot/projects/soc2008/gabor_textproc/grep/grep.c#69 (text+ko) ====

@@ -57,6 +57,10 @@
 nl_catd	 catalog;
 #endif
 
+/*
+ * Default messags to use when NLS is disabled or no catalogue
+ * is found.
+ */
 char	*errstr[] = {
 	"",
 /* 1*/	"(standard input)",
@@ -151,6 +155,9 @@
 
 extern char	*__progname;
 
+/*
+ * Prints usage information and returns 2.
+ */
 static void
 usage(void)
 {
@@ -213,7 +220,9 @@
 	{NULL,			no_argument,		NULL, 0}
 };
 
-
+/*
+ * Adds a searching pattern to the internal array.
+ */
 static void
 add_pattern(char *pat, size_t len)
 {
@@ -253,6 +262,9 @@
 	++patterns;
 }
 
+/*
+ * Adds an include/exclude pattern to the internal array.
+ */
 static void
 add_epattern(char *pat, size_t len)
 {
@@ -268,6 +280,9 @@
 	++epatterns;
 }
 
+/*
+ * Reads searching patterns from a file and adds them with add_pattern().
+ */
 static void
 read_patterns(const char *fn)
 {

==== //depot/projects/soc2008/gabor_textproc/grep/util.c#64 (text+ko) ====

@@ -53,13 +53,13 @@
 
 #include "grep.h"
 
-/*
- * Process a file line by line...
- */
-
 static int	 linesqueued;
 static int	 procline(struct str *l, int);
 
+/*
+ * Processes a directory when a recursive search is performed with
+ * the -R option.  Each appropriate file is passed to procfile().
+ */
 int
 grep_tree(char **argv)
 {
@@ -122,6 +122,10 @@
 	return (c);
 }
 
+/*
+ * Opens a file and processes it.  Each file is processed line-by-line
+ * passing the lines to  procline().
+ */
 int
 procfile(char *fn)
 {
@@ -215,6 +219,13 @@
 
 #define iswword(x)	(iswalnum((x)) || (x) == L'_')
 
+/*
+ * Processes a line comparing it with the specified patterns.  Each pattern
+ * is looped to be compared along with the full string, saving each and every
+ * match, which is necessary to colorize the output and to count the
+ * matches.  The matching lines are passed to printline() to display the
+ * appropriate output.
+ */
 static int
 procline(struct str *l, int nottext)
 {
@@ -313,6 +324,9 @@
 	return (c);
 }
 
+/*
+ * Safe malloc() for internal use.
+ */
 void *
 grep_malloc(size_t size)
 {
@@ -323,6 +337,9 @@
 	return (ptr);
 }
 
+/*
+ * Safe calloc() for internal use.
+ */
 void *
 grep_calloc(size_t nmemb, size_t size)
 {
@@ -333,6 +350,9 @@
 	return (ptr);
 }
 
+/*
+ * Safe realloc() for internal use.
+ */
 void *
 grep_realloc(void *ptr, size_t size)
 {
@@ -342,6 +362,9 @@
 	return (ptr);
 }
 
+/*
+ * Prints a matching line according to the command line options.
+ */
 void
 printline(struct str *line, int sep, regmatch_t *matches, int m)
 {