Rev 3559: Include better documentation about what is going on. (suggested by Bialix) in http://bzr.arbash-meinel.com/branches/bzr/1.6-dev/win32_find_files

[John Arbash Meinel]

At http://bzr.arbash-meinel.com/branches/bzr/1.6-dev/win32_find_files

------------------------------------------------------------
revno: 3559
revision-id: john at arbash-meinel.com-20080717151332-h4hwscv2jom8898r
parent: john at arbash-meinel.com-20080717144123-0ne8ig2vm9oehnn7
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: win32_find_files
timestamp: Thu 2008-07-17 10:13:32 -0500
message:
  Include better documentation about what is going on. (suggested by Bialix)
-------------- next part --------------
=== modified file 'bzrlib/_walkdirs_win32.pyx'
--- a/bzrlib/_walkdirs_win32.pyx	2008-07-17 14:41:23 +0000
+++ b/bzrlib/_walkdirs_win32.pyx	2008-07-17 15:13:32 +0000
@@ -196,6 +196,17 @@
         return statvalue
 
     def _get_files_in(self, directory, relprefix):
+        """Return the dirblock for all files in the given directory.
+
+        :param directory: A path that can directly access the files on disk.
+            Should be a Unicode object.
+        :param relprefix: A psuedo path for these files (as inherited from the
+            original 'prefix=XXX' when instantiating this class.)
+            It should be a UTF-8 string.
+        :return: A dirblock for all the files of the form
+            [(utf8_relpath, utf8_fname, kind, _Win32Stat, unicode_abspath)]
+        """
+        dirblock = self._get_files_in(top_slash, relprefix)
         cdef WIN32_FIND_DATAW search_data
         cdef HANDLE hFindFile
         cdef int last_err
@@ -221,13 +232,11 @@
                     continue
                 name_unicode = _get_name(&search_data)
                 name_utf8 = PyUnicode_AsUTF8String(name_unicode)
-                relpath = relprefix + name_utf8
-                abspath = directory + name_unicode
                 PyList_Append(dirblock, 
-                    (relpath, name_utf8, 
+                    (relprefix + name_utf8, name_utf8, 
                      self._get_kind(&search_data),
                      self._get_stat_value(&search_data),
-                     abspath))
+                     directory + name_unicode))
 
                 result = FindNextFileW(hFindFile, &search_data)
             # FindNextFileW sets GetLastError() == ERROR_NO_MORE_FILES when it
@@ -240,7 +249,9 @@
             result = FindClose(hFindFile)
             if result == 0:
                 last_err = GetLastError()
-                pass
+                # TODO: We should probably raise an exception if FindClose
+                #       returns an error, however, I don't want to supress an
+                #       earlier Exception, so for now, I'm ignoring this
         return dirblock
 
     cdef _update_pending(self):