misc docs

git-svn-id: file:///home/or/svnrepo/updater/trunk@17315 55e972cd-5a19-0410-ae62-a4d7a52db4cd

5 files changed, 60 insertions, 5 deletions

diff --git a/TODO b/TODO
index eaa8d1e..01c1966 100644
--- a/TODO
+++ b/TODO
@@ -1,3 +1,6 @@
+03:07 < nickm> ok.  tomorrow morning I try to get messaging sorted, and try to
+               write up a registry-based exe version checker.
+
 - Download improvements.
   - Back off on download failure.
   - Handle full stalled file in download.
diff --git a/doc/interface.txt b/doc/interface.txt
new file mode 100644
index 0000000..dd5c9ae
--- /dev/null
+++ b/doc/interface.txt
@@ -0,0 +1,45 @@
+
+
+
+
+
+Thandy client interface:
+
+   thandy-client update [options] [bundlename...]
+
+Recognized options are:
+
+   --repo=<dir>    Store downloaded, finished information under <dir>.
+                   Defaults to ~/.thandy/cache
+
+   --no-download   Only decide what to download; don't actually download
+                   anything.
+
+   --loop          Do not exit after we have nothing more to download; keep
+                   waiting until there's something to do.
+
+   --no-packagesys Do not ask any underlying package system about what
+                   versions of things are installed.  Assume we need to
+                   fetch all packages not in the cache.
+
+   --install       Try to install packages after downloading them.
+
+   --socks-port=<port>
+                   Run all network operations over the SOCKS4a server at
+                   localhost:<port>
+
+   --debug|--info|--warn
+                   Set logging severity.
+
+
+   --force-check
+                   Download a fresh version of the timestamp file, whether
+                   we need it or not.
+
+
+02:55 < nickm> Right now, for a quick-and-dirty thing, vidalia can notice the 
+               specific form of the "Ready to install files:" message.  It can 
+               turn into something more formal later.
+02:56 < nickm> The only 'suggestions' thandy-client understands now are ones 
+               from command-line options, all of which are documented.
+02:56 < armadev> ok
diff --git a/lib/thandy/ClientCLI.py b/lib/thandy/ClientCLI.py
index 178c887..55d52c6 100644
--- a/lib/thandy/ClientCLI.py
+++ b/lib/thandy/ClientCLI.py
@@ -145,7 +145,7 @@ def usage():
     print "Known commands:"
     print "  update [--repo=repository] [--no-download] [--loop]"
     print "         [--no-packagesys] [--install] [--socks-port=port]"
-    print "         [--debug|--info|--warn]"
+    print "         [--debug|--info|--warn] [--force-check]"
     sys.exit(1)
 
 def main():
diff --git a/lib/thandy/download.py b/lib/thandy/download.py
index 2f98b30..d7fa19a 100644
--- a/lib/thandy/download.py
+++ b/lib/thandy/download.py
@@ -142,8 +142,9 @@ class DownloadJob:
            store it in targetPath.  Store partial results in tmpPath;
            if there is already a file in tmpPath, assume that it is an
            incomplete download. If wantHash, reject the file unless
-           the hash is as given.  If useTor, use a socks connection."""
-        #DOCDODC repofile
+           the hash is as given.  If useTor, use a socks connection.
+           If repoFile, use that RepositoryFile to validate the downloaded
+           data."""
         self._destPath = targetPath
         self._tmpPath = tmpPath
         self._wantHash = wantHash
@@ -196,7 +197,8 @@ class DownloadJob:
             return False
 
     def _checkTmpFile(self):
-        """DOCDOC"""
+        """Helper: check whether the downloaded temporary file matches
+           the hash and/or format we need."""
         if self._wantHash and not self._repoFile:
             gotHash = thandy.formats.getFileDigest(self._tmpPath)
             if gotHash != self._wantHash:
@@ -204,6 +206,7 @@ class DownloadJob:
         elif self._repoFile:
             self._repoFile.checkFile(self._tmpPath, self._wantHash)
 
+
     def _download(self):
         # Implementation function.  Unlike download(), can throw exceptions.
         f_in = f_out = None
@@ -215,7 +218,8 @@ class DownloadJob:
             except thandy.Exception:
                 pass
             else:
-                # What luck!  This file was what we wanted.
+                # What luck!  This stalled file was what we wanted.
+                # (This happens mostly with )
                 thandy.util.ensureParentDir(self._destPath)
                 thandy.util.moveFile(self._tmpPath, self._destPath)
                 return
diff --git a/lib/thandy/util.py b/lib/thandy/util.py
index 00efb59..f2bac17 100644
--- a/lib/thandy/util.py
+++ b/lib/thandy/util.py
@@ -20,6 +20,9 @@ import thandy.keys
 import thandy.master_keys
 
 def moveFile(fromLocation, toLocation):
+    """Move the file from fromLocation to toLocation, removing any file
+       in toLocation.
+    """
     if sys.platform in ('cygwin', 'win32'):
         # Win32 doesn't let rename replace an existing file.
         try: