PERFORCE change 130698 for review

[Garrett Cooper]

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

Change 130698 by gcooper at shiina-ibook on 2007/12/12 11:58:08

	- Add more Doxygenated comments.
	- Replace while loops with slightly smarter for-loops.
	- Make some logic a bit more straightforward.

Affected files ...

.. //depot/projects/soc2007/revised_fbsd_pkgtools/pkg_revised/v2/contrib/libpkg/pkg_freebsd_contents.c#3 edit

Differences ...

==== //depot/projects/soc2007/revised_fbsd_pkgtools/pkg_revised/v2/contrib/libpkg/pkg_freebsd_contents.c#3 (text+ko) ====

@@ -74,7 +74,7 @@
 	unsigned int pos;
 
 	cont = malloc(sizeof(struct pkg_freebsd_contents));
-	if (!cont)
+	if (cont == NULL)
 		return NULL;
 
 	cont->cnts_file = NULL;
@@ -87,7 +87,7 @@
 		cont->lines = NULL;
 	} else {
 		cont->file = malloc(length + 1);
-		if (!cont->file) {
+		if (cont->file == NULL) {
 			free(cont);
 			return NULL;
 		}
@@ -95,12 +95,11 @@
 		cont->file[length] = '\0';
 		cont->lines = NULL;
 
-		pos = 0;
 		cont->line_count = 0;
-		while (pos != length) {
+		/* Scan through beforehand, counting newlines.. */
+		for (pos = 0; pos != length; pos++) {
 			if (cont->file[pos] == '\n')
 				cont->line_count++;
-			pos++;
 		}
 		/* Check the last line contains data */
 		if (pos > 0 && cont->file[pos-1] != '\n')
@@ -112,54 +111,66 @@
 		}
 		cont->lines = malloc(sizeof(struct pkg_freebsd_contents_line) *
 		    cont->line_count);
-		if (!cont->lines) {
+		if (cont->lines == NULL) {
 			pkg_freebsd_contents_free(cont);
 			return NULL;
 		}
 
 		/*
-		 * Make each line in cont->lines point to the start of it's line
-		 * and be a valid string
+		 * Make each line in cont->lines point to the start of its
+		 * line and null terminate the last string. 
 		 */
 		cont->lines[0].line = cont->file;
 		cont->lines[0].data = NULL;
-		pos = 1;
-		while (pos < cont->line_count) {
+		for (pos = 1; pos < cont->line_count; pos++) {
+
 			cont->lines[pos].data = NULL;
 			cont->lines[pos].line = strchr(cont->lines[pos-1].line, '\n');
-			if (cont->lines[pos].line) {
-				/* Terminate the last line */
-				cont->lines[pos].line[0] = '\0';
-				cont->lines[pos].line++;
-			} else
+
+			/* No more newlines? We're done then.. */
+			if (cont->lines[pos].line == NULL)
 				break;
-			pos++;
+
+			/* Terminate the last line */
+			cont->lines[pos].line[0] = '\0';
+			cont->lines[pos].line++;
+
 		}
-		/* The last line may need to be terminated at the correct place */
+		/*
+		 * The last line needs to be NULL terminated if it's just a
+		 * newline. 
+		 */
 		pos = strlen(cont->lines[cont->line_count-1].line);
-		if (cont->lines[cont->line_count-1].line[--pos] == '\n') {
+		if (cont->lines[cont->line_count-1].line[--pos] == '\n')
 			cont->lines[cont->line_count-1].line[pos] = '\0';
-		}
 
 		/*
-	         * Set the data part of the line. ie not the control word 
-	         * Set the line_type
+	         * 1. Set the data part of the line, i.e. not the control word 
+	         * 2. Set the line_type for the pkg_freebsd_contents_line
+	         *     structure accordingly.. 
 	         */
 		for(pos = 0; pos < cont->line_count; pos++) {
 			char *space;
 
+			/*
+			 * Lines to skip -- ones which don't start with '@'
+			 * (control directives) or contain the @ignore
+			 * directive.
+			 */
 			if (cont->lines[pos].line[0] != '@') {
 				cont->lines[pos].line_type = PKG_LINE_FILE;
 				assert(cont->lines[pos].data == NULL);
 				continue;
-			} else if (!strcmp(cont->lines[pos].line, "@ignore")) {
+			} else if (strcmp(cont->lines[pos].line, "@ignore") ==
+			    0) {
 				cont->lines[pos].line_type = PKG_LINE_IGNORE;
 				assert(cont->lines[pos].data == NULL);
 				continue;
 			}
 
+			/* Skip ahead to the first space. */
 			space = strchr(cont->lines[pos].line, ' ');
-			if (space && space[0] != '\0') {
+			if (space != NULL && space[0] != '\0') {
 				space[0] = '\0';
 				space++;
 				if (space[0] != '\0')
@@ -170,7 +181,7 @@
 				return NULL;
 			}
 
-			/* Get the correct line type for the line */
+			/* Parse in the line type properly.. */
 			if (strcmp(cont->lines[pos].line, "@comment") == 0) {
 				cont->lines[pos].line_type = PKG_LINE_COMMENT;
 			} else if (strcmp(cont->lines[pos].line, "@name") ==
@@ -225,9 +236,8 @@
 	if (contents == NULL || data == NULL)
 		return -1;
 
-	if (!(type > 0 && type <= PKG_LINE_FILE)) {
+	if (type <= 0 || PKG_LINE_FILE < type)
 		return -1;
-	}
 
 	/* Add the lines to the +CONTENTS file */
 	contents->line_size += sizeof(struct pkg_freebsd_contents_line);
@@ -320,10 +330,13 @@
 	}
 
 	data = pkgfile_get_data(file);
+
 	if (data == NULL)
 		return -1;
+
 	MD5Data(data, pkgfile_get_size(file), md5);
 	snprintf(tmp, 37, "MD5:%s", md5);
+
 	if (pkg_freebsd_contents_add_line(contents, PKG_LINE_COMMENT, tmp)
 	    != 0) {
 		return -1;
@@ -336,22 +349,28 @@
 	return 0;
 }
 
-/**
- * Gets the given line from the contents file
+/*
+ * @brief Get a given line from the contents file.
+ * @param contents The contents file to return the line from.
+ * @param line_num The line to return.
+ * @return NULL on error (index out of bounds, contents NULL);
+ *     otherwise return the line.
  */
 struct pkg_freebsd_contents_line*
 pkg_freebsd_contents_get_line(struct pkg_freebsd_contents *contents,
-		unsigned int line)
+		unsigned int line_num)
 {
-	if (contents == NULL)
+	if (contents == NULL || contents->line_count < line_num)
 		return NULL;
 
-	if (line > contents->line_count)
-		return NULL;
-
-	return &contents->lines[line];
+	return &contents->lines[line_num];
 }
 
+/*
+ * @brief Update the prefix for +CONTENTS
+ * @param contents The pkg_freebsd_contents structure that will be updated.
+ * @param prefix The package prefix to update contents to.
+ */
 int
 pkg_freebsd_contents_update_prefix(struct pkg_freebsd_contents *contents,
     const char *prefix)
@@ -363,22 +382,33 @@
 
 	/* Find the package prefix and change it */
 	for (pos = 0; pos < contents->line_count; pos++) {
+
 		if (contents->lines[pos].line_type == PKG_LINE_CWD) {
-			if (contents->cnts_prefix != NULL) {
+
+			if (contents->cnts_prefix != NULL)
 				free(contents->cnts_prefix);
-			}
+
 			contents->cnts_prefix = strdup(prefix);
 			contents->lines[pos].data = contents->cnts_prefix;
 			break;
+
 		}
+
 	}
+
 	if (contents->cnts_file != NULL) {
 		pkgfile_free(contents->cnts_file);
 		contents->cnts_file = NULL;
 	}
 	return 0;
+
 }
 
+/**
+ * Get the +CONTENTS file associated with the pkg_freebsd_contents structure.
+ *
+ * @return NULL on error or the pkgfile associated with +CONTENTS on success.
+ */
 struct pkgfile *
 pkg_freebsd_contents_get_file(struct pkg_freebsd_contents *contents)
 {
@@ -389,9 +419,14 @@
 
 	if (contents->cnts_file == NULL) {
 		contents->cnts_file = pkgfile_new_regular("+CONTENTS", "", 0);
+
 		if (contents->cnts_file == NULL)
 			return NULL;
 
+		/*
+		 * Iterate through the file line by line, appending all of the
+		 * data from contents to contents->cnts_file.
+		 */
 		for (pos = 0; pos < contents->line_count; pos++) {
 			struct pkg_freebsd_contents_line *line;
 			char *data;
@@ -415,6 +450,7 @@
 
 /**
  * Frees a contents struct
+ * @return -1 on failure, 0 on success.
  */
 int
 pkg_freebsd_contents_free(struct pkg_freebsd_contents *contents)