From 2b9d624d1df1f1faadb95077c2d0ba01c69ac1c2 Mon Sep 17 00:00:00 2001
From: Olaf Barthel <obarthel@gmx.net>
Date: Mon, 2 Oct 2006 07:15:37 +0000
Subject: [PATCH] - Added some documenting comments to the source code.

git-svn-id: file:///Users/olsen/Code/migration-svn-zu-git/logical-line-staging/clib2/trunk@15157 87f5fb63-7c3d-0410-a384-fd976d0f7a62
---
 library/libgen_basename.c | 14 ++++++++++++--
 library/libgen_dirname.c  | 15 +++++++++++++--
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/library/libgen_basename.c b/library/libgen_basename.c
index 023c2dc..5edd4f6 100644
--- a/library/libgen_basename.c
+++ b/library/libgen_basename.c
@@ -1,5 +1,5 @@
 /*
- * $Id: libgen_basename.c,v 1.7 2006-09-25 18:19:44 obarthel Exp $
+ * $Id: libgen_basename.c,v 1.8 2006-10-02 07:15:37 obarthel Exp $
  *
  * :ts=4
  *
@@ -60,6 +60,7 @@ basename(const char *path)
 	else
 		SHOWSTRING(path);
 
+	/* An empty path always comes out as the "current directory". */
 	if(path == NULL || path[0] == '\0')
 	{
 		str = ".";
@@ -67,15 +68,18 @@ basename(const char *path)
 	}
 	else
 	{
+		/* Strip all trailing slashes. */
 		len = strlen(path);
-
 		while(len > 0 && path[len-1] == '/')
 			len--;
 
+		/* Is there anything left? */
 		if(len > 0)
 		{
 			size_t i;
 
+			/* Return what follows the last slash in the path. That's
+			   usually a file or directory name. */
 			str = path;
 
 			for(i = len - 1 ; ; i--)
@@ -93,6 +97,9 @@ basename(const char *path)
 			}
 		}
 
+		/* If the whole operation produced an empty string, then it
+		   means that we dealt with a string which consisted entirely
+		   of slashes. And that's what we will return. */
 		if(len == 0)
 		{
 			str = "/";
@@ -100,6 +107,9 @@ basename(const char *path)
 		}
 	}
 
+	/* Truncate the path name we can return. This function always returns
+	   a valid pointer rather than NULL because some software expects it
+	   to do so (I blame the specifications). */
 	if(len >= sizeof(new_path))
 		len = sizeof(new_path)-1;
 
diff --git a/library/libgen_dirname.c b/library/libgen_dirname.c
index 4578ece..81a62f6 100644
--- a/library/libgen_dirname.c
+++ b/library/libgen_dirname.c
@@ -1,5 +1,5 @@
 /*
- * $Id: libgen_dirname.c,v 1.7 2006-09-25 18:19:44 obarthel Exp $
+ * $Id: libgen_dirname.c,v 1.8 2006-10-02 07:15:37 obarthel Exp $
  *
  * :ts=4
  *
@@ -60,16 +60,18 @@ dirname(const char *path)
 	else
 		SHOWSTRING(path);
 
+	/* An empty path always comes out as the "current directory". */
 	str = ".";
 	len = 1;
 
 	if(path != NULL && path[0] != '\0')
 	{
+		/* Strip all trailing slashes. */
 		len = strlen(path);
-
 		while(len > 1 && path[len-1] == '/')
 			len--;
 
+		/* Is there anything left? */
 		if(len > 0)
 		{
 			size_t i;
@@ -78,9 +80,15 @@ dirname(const char *path)
 			{
 				if(path[i] == '/')
 				{
+					/* Return everything up to, but not including
+					   the last slash in the path. That's usually
+					   the directory name. */
 					str = path;
 					len = i;
 
+					/* If that produces an empty string, it means
+					   that the entire string consists of slash
+					   characters. We'll return only the first. */
 					if(i == 0)
 						len++;
 
@@ -93,6 +101,9 @@ dirname(const char *path)
 		}
 	}
 
+	/* Truncate the path name we can return. This function always returns
+	   a valid pointer rather than NULL because some software expects it
+	   to do so (I blame the specifications). */
 	if(len >= sizeof(new_path))
 		len = sizeof(new_path)-1;