* merged daniels wonderful doxygen work

Patches applied:

 * dburrows@debian.org--2005/apt--0--base-0
   tag of mvo@debian.org--2005/apt--debian-experimental--0--patch-9

 * dburrows@debian.org--2005/apt--doxygen--0--base-0
   tag of dburrows@debian.org--2005/apt--0--base-0

 * dburrows@debian.org--2005/apt--doxygen--0--patch-1
   Generate Doxygen output in build/doc/doxygen if Doxygen is installed.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-2
   Partially document the acquire item objects.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-3
   Add an 'acquire' group to collect the stuff related to Acquire.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-4
   Don't pick up emacs autosaves when generating the list of doxygen inputs.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-5
   Don't include redundant scope information in the doxygen output.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-6
   Write more general Acquire documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-7
   I don't know why, but stuff just appeared in my tree.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-8
   Write/edit more Acquire documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-9
   Document pkgAcquire::ItemDesc and pkgAcquire::Queue.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-10
   Document UriIterator (left out documentation of the standard iterator operators).

 * dburrows@debian.org--2005/apt--doxygen--0--patch-11
   Give pkgAcquire::Queue a brief description.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-12
   Add a brief description to pkgAcquire::Item.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-13
   Add a brief description to the DiffInfo class.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-14
   Document pkgAcquire::MethodConfig.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-15
   Document pkgAcquireStatus

 * dburrows@debian.org--2005/apt--doxygen--0--patch-16
   Edit the pkgAcquire::Item documentation to be more in line with how Acquire is documented.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-17
   Document pkgAcqDiffIndex.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-18
   Document the Md5Hash parameter to pkgAcquire::Item::Done.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-19
   Fix a spelling error

 * dburrows@debian.org--2005/apt--doxygen--0--patch-20
   Document pkgAcqIndexDiffs and fix up some previously written documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-21
   Mark the brief descriptions in the acquire item documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-22
   Add documentation about the format of the Message parameter to Done&friends.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-23
   Document pkgAcqIndex.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-24
   Document pkgAcqIndexTrans.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-25
   Autogenerate Doxyfile when Doxyfile.in is modified.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-26
   Check for graphviz in configure.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-27
   Fix the detection of dot.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-28
   If dot is detected, use it to build the documentation.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-29
   Argh, pot update.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-30
   Require graphviz when building the Debian packages.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-31
   Document IndexTarget.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-32
   Consistently capitalize the first word following \param.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-33
   Document pkgAcqMetaSig.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-34
   Be a bit clearer about just what a pkgAcquire::Item is.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-35
   Document pkgAcqMetaIndex.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-36
   Document pkgAcqArchive

 * dburrows@debian.org--2005/apt--doxygen--0--patch-37
   Document pkgAcqFile

 * dburrows@debian.org--2005/apt--doxygen--0--patch-38
   Apply patches from mvo

 * dburrows@debian.org--2005/apt--doxygen--0--patch-39
   Update the Doxyfile template.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-40
   Enable BUILTIN_STL_SUPPORT.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-41
   Whoops: \e, not \i, is used to enable italics.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-42
   Editorial changes and clarifications to the documentation in  acquire-item.h

 * dburrows@debian.org--2005/apt--doxygen--0--patch-43
   Clean out the old doxygen output before generating new output.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-44
   Fix setting and using the DOT_PATH doxygen configuration parameter.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-45
   Make the documentation of ��pkgAcquire::MethodConfig::SendConfig somewhat more accurate.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-46
   Partially document pkgAcquire::Worker.

 * dburrows@debian.org--2005/apt--doxygen--0--patch-47
   Finish documenting pkgAcquire::Worker

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--base-0
   tag of dburrows@debian.org--2005/apt--doxygen--0--patch-37

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--patch-1
   * some documentation updates

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--patch-2
   * apt-pkg/acquire-item.h: reviewed and some modifications

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--patch-3
   * minor doc update

 * michael.vogt@ubuntu.com--laptop/apt--doxygen--0--patch-4
   * updated after the input from dburrows

 * mvo@debian.org--2005/apt--debian-sid--0--base-0
   tag of michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-71

 * mvo@debian.org--2005/apt--debian-sid--0--patch-1
   * merged with apt--mvo--0

 * mvo@debian.org--2005/apt--debian-sid--0--patch-2
   * merged with apt--mvo

 * mvo@debian.org--2005/apt--debian-sid--0--patch-3
   * updated apt-all.pot

 * mvo@debian.org--2005/apt--debian-sid--0--patch-4
   * merged with apt--mvo

 * mvo@debian.org--2005/apt--debian-sid--0--patch-5
   * merge with apt--mvo--0

 * mvo@debian.org--2005/apt--debian-sid--0--patch-6
   * merge with apt--mvo

 * mvo@debian.org--2005/apt--debian-sid--0--patch-7
   * applied patch from Petr Vandrovec to fix http download corruption

 * mvo@debian.org--2005/apt--debian-sid--0--patch-8
   * merged with apt--mvo, regenerated the po files

 * mvo@debian.org--2005/apt--debian-sid--0--patch-9
   * merged with apt--mvo

5 files changed, 1393 insertions, 84 deletions

diff --git a/apt-pkg/acquire-item.cc b/apt-pkg/acquire-item.cc
index 9fb7b57c2..7c1626bff 100644
--- a/apt-pkg/acquire-item.cc
+++ b/apt-pkg/acquire-item.cc
@@ -362,7 +362,7 @@ void pkgAcqIndexDiffs::Failed(string Message,pkgAcquire::MethodConfig *Cnf)
 {
    if(Debug)
       std::clog << "pkgAcqIndexDiffs failed: " << Desc.URI << std::endl
-		<< "Falling back to normal index file aquire" << std::endl;
+		<< "Falling back to normal index file acquire" << std::endl;
    new pkgAcqIndex(Owner, RealURI, Description,Desc.ShortDesc, 
 		   ExpectedMD5);
    Finish();
diff --git a/apt-pkg/acquire-item.h b/apt-pkg/acquire-item.h
index 34fcc2a76..323dff256 100644
--- a/apt-pkg/acquire-item.h
+++ b/apt-pkg/acquire-item.h
@@ -31,73 +31,283 @@
 #pragma interface "apt-pkg/acquire-item.h"
 #endif 
 
-// Item to acquire
+/** \addtogroup acquire
+ *  @{
+ *
+ *  \file acquire-item.h
+ */
+
+/** \brief Represents the process by which a pkgAcquire object should
+ *  retrieve a file or a collection of files.
+ *
+ *  By convention, Item subclasses should insert themselves into the
+ *  acquire queue when they are created by calling QueueURI(), and
+ *  remove themselves by calling Dequeue() when either Done() or
+ *  Failed() is invoked.  Item objects are also responsible for
+ *  notifying the download progress indicator (accessible via
+ *  #Owner->Log) of their status.
+ *
+ *  \see pkgAcquire
+ */
 class pkgAcquire::Item
 {  
    protected:
    
-   // Some private helper methods for registering URIs
+   /** \brief The acquire object with which this item is associated. */
    pkgAcquire *Owner;
+
+   /** \brief Insert this item into its owner's queue.
+    *
+    *  \param ItemDesc Metadata about this item (its URI and
+    *  description).
+    */
    inline void QueueURI(ItemDesc &Item)
                  {Owner->Enqueue(Item);};
+
+   /** \brief Remove this item from its owner's queue. */
    inline void Dequeue() {Owner->Dequeue(this);};
    
-   // Safe rename function with timestamp preservation
+   /** \brief Rename a file without modifying its timestamp.
+    *
+    *  Many item methods call this as their final action.
+    *
+    *  \param From The file to be renamed.
+    *
+    *  \param To The new name of #From.  If #To exists it will be
+    *  overwritten.
+    */
    void Rename(string From,string To);
    
    public:
 
-   // State of the item
-   enum {StatIdle, StatFetching, StatDone, StatError, StatAuthError} Status;
+   /** \brief The current status of this item. */
+   enum ItemState
+     {
+       /** \brief The item is waiting to be downloaded. */
+       StatIdle,
+
+       /** \brief The item is currently being downloaded. */
+       StatFetching,
+
+       /** \brief The item has been successfully downloaded. */
+       StatDone,
+
+       /** \brief An error was encountered while downloading this
+	*  item.
+	*/
+       StatError,
+
+       /** \brief The item was downloaded but its authenticity could
+	*  not be verified.
+	*/
+       StatAuthError
+     } Status;
+
+   /** \brief Contains a textual description of the error encountered
+    *  if #Status is #StatError or #StatAuthError.
+    */
    string ErrorText;
+
+   /** \brief The size of the object to fetch. */
    unsigned long FileSize;
-   unsigned long PartialSize;   
+
+   /** \brief How much of the object was already fetched. */
+   unsigned long PartialSize;
+
+   /** \brief If not \b NULL, contains the name of a subprocess that
+    *  is operating on this object (for instance, "gzip" or "gpgv").
+    */
    const char *Mode;
+
+   /** \brief A client-supplied unique identifier.
+    * 
+    *  This field is initalized to 0; it is meant to be filled in by
+    *  clients that wish to use it to uniquely identify items.
+    *
+    *  \todo it's unused in apt itself
+    */
    unsigned long ID;
+
+   /** \brief If \b true, the entire object has been successfully fetched.
+    *
+    *  Subclasses should set this to \b true when appropriate.
+    */
    bool Complete;
+
+   /** \brief If \b true, the URI of this object is "local".
+    *
+    *  The only effect of this field is to exclude the object from the
+    *  download progress indicator's overall statistics.
+    */
    bool Local;
 
-   // Number of queues we are inserted into
+   /** \brief The number of fetch queues into which this item has been
+    *  inserted.
+    *
+    *  There is one queue for each source from which an item could be
+    *  downloaded.
+    *
+    *  \sa pkgAcquire
+    */
    unsigned int QueueCounter;
    
-   // File to write the fetch into
+   /** \brief The name of the file into which the retrieved object
+    *  will be written.
+    */
    string DestFile;
 
-   // Action members invoked by the worker
+   /** \brief Invoked by the acquire worker when the object couldn't
+    *  be fetched.
+    *
+    *  This is a branch of the continuation of the fetch process.
+    *
+    *  \param Message An RFC822-formatted message from the acquire
+    *  method describing what went wrong.  Use LookupTag() to parse
+    *  it.
+    *
+    *  \param Cnf The method via which the worker tried to fetch this object.
+    *
+    *  \sa pkgAcqMethod
+    */
    virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
+
+   /** \brief Invoked by the acquire worker when the object was
+    *  fetched successfully.
+    *
+    *  Note that the object might \e not have been written to
+    *  DestFile; check for the presence of an Alt-Filename entry in
+    *  Message to find the file to which it was really written.
+    *
+    *  Done is often used to switch from one stage of the processing
+    *  to the next (e.g. fetching, unpacking, copying).  It is one
+    *  branch of the continuation of the fetch process.
+    *
+    *  \param Message Data from the acquire method.  Use LookupTag()
+    *  to parse it.
+    *  \param Size The size of the object that was fetched.
+    *  \param Md5Hash The MD5Sum of the object that was fetched.
+    *  \param Cnf The method via which the object was fetched.
+    *
+    *  \sa pkgAcqMethod
+    */
    virtual void Done(string Message,unsigned long Size,string Md5Hash,
 		     pkgAcquire::MethodConfig *Cnf);
+
+   /** \brief Invoked when the worker starts to fetch this object.
+    *
+    *  \param Message RFC822-formatted data from the worker process.
+    *  Use LookupTag() to parse it.
+    *
+    *  \param Size The size of the object being fetched.
+    *
+    *  \sa pkgAcqMethod
+    */
    virtual void Start(string Message,unsigned long Size);
+
+   /** \brief Custom headers to be sent to the fetch process.
+    *
+    *  \return a string containing RFC822-style headers that are to be
+    *  inserted into the 600 URI Acquire message sent to the fetch
+    *  subprocess.  The headers are inserted after a newline-less
+    *  line, so they should (if nonempty) have a leading newline and
+    *  no trailing newline.
+    */
    virtual string Custom600Headers() {return string();};
+
+   /** \brief A "descriptive" URI-like string.
+    *
+    *  \return a URI that should be used to describe what is being fetched.
+    */
    virtual string DescURI() = 0;
+   /** \brief Short item description.
+    *
+    *  \return a brief description of the object being fetched.
+    */
    virtual string ShortDesc() {return DescURI();}
+
+   /** \brief Invoked by the worker when the download is completely done. */
    virtual void Finished() {};
    
-   // Inquire functions
+   /** \brief MD5Sum.
+    *
+    *  \return the MD5Sum of this object, if applicable; otherwise, an
+    *  empty string.
+    */
    virtual string MD5Sum() {return string();};
+
+   /** \return the acquire process with which this item is associated. */
    pkgAcquire *GetOwner() {return Owner;};
+
+   /** \return \b true if this object is being fetched from a trusted source. */
    virtual bool IsTrusted() {return false;};
-   
+
+   /** \brief Initialize an item.
+    *
+    *  Adds the item to the list of items known to the acquire
+    *  process, but does not place it into any fetch queues (you must
+    *  manually invoke QueueURI() to do so).
+    *
+    *  Initializes all fields of the item other than Owner to 0,
+    *  false, or the empty string.
+    *
+    *  \param Owner The new owner of this item.
+    */
    Item(pkgAcquire *Owner);
+
+   /** \brief Remove this item from its owner's queue by invoking
+    *  pkgAcquire::Remove.
+    */
    virtual ~Item();
 };
 
-// item for index diffs
-
+/** \brief Information about an index patch (aka diff). */
 struct DiffInfo {
+   /** The filename of the diff. */
    string file;
+
+   /** The sha1 hash of the diff. */
    string sha1;
+
+   /** The size of the diff. */
    unsigned long size;
 };
 
+/** \brief An item that is responsible for fetching an index file of
+ *  package list diffs and starting the package list's download.
+ *
+ *  This item downloads the Index file and parses it, then enqueues
+ *  additional downloads of either the individual patches (using
+ *  pkgAcqIndexDiffs) or the entire Packages file (using pkgAcqIndex).
+ *
+ *  \sa pkgAcqIndexDiffs, pkgAcqIndex
+ */
 class pkgAcqDiffIndex : public pkgAcquire::Item
 {
  protected:
+   /** \brief If \b true, debugging information will be written to std::clog. */
    bool Debug;
+
+   /** \brief The item that is currently being downloaded. */
    pkgAcquire::ItemDesc Desc;
+
+   /** \brief The URI of the index file to recreate at our end (either
+    *  by downloading it or by applying partial patches).
+    */
    string RealURI;
+
+   /** \brief The MD5Sum that the real index file should have after
+    *  all patches have been applied.
+    */
    string ExpectedMD5;
+
+   /** \brief The index file which will be patched to generate the new
+    *  file.
+    */
    string CurrentPackagesFile;
+
+   /** \brief A description of the Packages file (stored in
+    *  pkgAcquire::ItemDesc::Description).
+    */
    string Description;
 
  public:
@@ -108,54 +318,199 @@ class pkgAcqDiffIndex : public pkgAcquire::Item
    virtual string DescURI() {return RealURI + "Index";};
    virtual string Custom600Headers();
 
-   // helpers
+   /** \brief Parse the Index file for a set of Packages diffs.
+    *
+    *  Parses the Index file and creates additional download items as
+    *  necessary.
+    *
+    *  \param IndexDiffFile The name of the Index file.
+    *
+    *  \return \b true if the Index file was successfully parsed, \b
+    *  false otherwise.
+    */
    bool ParseDiffIndex(string IndexDiffFile);
    
+
+   /** \brief Create a new pkgAcqDiffIndex.
+    *
+    *  \param Owner The Acquire object that owns this item.
+    *
+    *  \param URI The URI of the list file to download.
+    *
+    *  \param URIDesc A long description of the list file to download.
+    *
+    *  \param ShortDesc A short description of the list file to download.
+    *
+    *  \param ExpectedMD5 The list file's MD5 signature.
+    */
    pkgAcqDiffIndex(pkgAcquire *Owner,string URI,string URIDesc,
-		   string ShortDesct, string ExpectedMD5);
+		   string ShortDesc, string ExpectedMD5);
 };
 
+/** \brief An item that is responsible for fetching all the patches
+ *  that need to be applied to a given package index file.
+ *
+ *  After downloading and applying a single patch, this item will
+ *  enqueue a new pkgAcqIndexDiffs to download and apply the remaining
+ *  patches.  If no patch can be found that applies to an intermediate
+ *  file or if one of the patches cannot be downloaded, falls back to
+ *  downloading the entire package index file using pkgAcqIndex.
+ *
+ *  \sa pkgAcqDiffIndex, pkgAcqIndex
+ */
 class pkgAcqIndexDiffs : public pkgAcquire::Item
 {
+   private:
+
+   /** \brief Queue up the next diff download.
+    *
+    *  Search for the next available diff that applies to the file
+    *  that currently exists on disk, and enqueue it by calling
+    *  QueueURI().
+    *
+    *  \return \b true if an applicable diff was found, \b false
+    *  otherwise.
+    */
+   bool QueueNextDiff();
+
+   /** \brief Handle tasks that must be performed after the item
+    *  finishes downloading.
+    *
+    *  Dequeues the item and checks the resulting file's md5sum
+    *  against ExpectedMD5 after the last patch was applied.
+    *  There is no need to check the md5/sha1 after a "normal" 
+    *  patch because QueueNextDiff() will check the sha1 later.
+    *
+    *  \param allDone If \b true, the file was entirely reconstructed,
+    *  and its md5sum is verified. 
+    */
+   void Finish(bool allDone=false);
+
    protected:
+
+   /** \brief If \b true, debugging output will be written to
+    *  std::clog.
+    */
    bool Debug;
+
+   /** \brief A description of the item that is currently being
+    *  downloaded.
+    */
    pkgAcquire::ItemDesc Desc;
+
+   /** \brief The URI of the package index file that is being
+    *  reconstructed.
+    */
    string RealURI;
+
+   /** \brief The MD5Sum of the package index file that is being
+    *  reconstructed.
+    */
    string ExpectedMD5;
 
-   // this is the SHA-1 sum we expect after the patching
+   /** A description of the file being downloaded. */
    string Description;
+
+   /** The patches that remain to be downloaded, including the patch
+    *  being downloaded right now.  This list should be ordered so
+    *  that each diff appears before any diff that depends on it.
+    *
+    *  \todo These are indexed by sha1sum; why not use some sort of
+    *  dictionary instead of relying on ordering and stripping them
+    *  off the front?
+    */
    vector<DiffInfo> available_patches;
-   enum {StateFetchIndex,StateFetchDiff,StateUnzipDiff,StateApplyDiff} State;
+   /** The current status of this patch. */
+   enum DiffState
+     {
+	/** \brief The diff is in an unknown state. */
+	 StateFetchUnkown,
+
+	 /** \brief The diff is currently being fetched. */
+	 StateFetchDiff,
+	 
+	 /** \brief The diff is currently being uncompressed. */
+	 StateUnzipDiff,
+
+	 /** \brief The diff is currently being applied. */
+	 StateApplyDiff
+   } State;
 
    public:
    
-   // Specialized action members
+   /** \brief Called when the patch file failed to be downloaded.
+    *
+    *  This method will fall back to downloading the whole index file
+    *  outright; its arguments are ignored.
+    */
    virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
+
    virtual void Done(string Message,unsigned long Size,string Md5Hash,
 		     pkgAcquire::MethodConfig *Cnf);
    virtual string DescURI() {return RealURI + "Index";};
 
-   // various helpers
-   bool QueueNextDiff();
-   bool ApplyDiff(string PatchFile);
-   void Finish(bool allDone=false);
-
+   /** \brief Create an index diff item.
+    *
+    *  After filling in its basic fields, this invokes Finish(true) if
+    *  #diffs is empty, or QueueNextDiff() otherwise.
+    *
+    *  \param Owner The pkgAcquire object that owns this item.
+    *
+    *  \param URI The URI of the package index file being
+    *  reconstructed.
+    *
+    *  \param URIDesc A long description of this item.
+    *
+    *  \param ShortDesc A brief description of this item.
+    *
+    *  \param ExpectedMD5 The expected md5sum of the completely
+    *  reconstructed package index file; the index file will be tested
+    *  against this value when it is entirely reconstructed.
+    *
+    *  \param diffs The remaining diffs from the index of diffs.  They
+    *  should be ordered so that each diff appears before any diff
+    *  that depends on it.
+    */
    pkgAcqIndexDiffs(pkgAcquire *Owner,string URI,string URIDesc,
-		    string ShortDesct, string ExpectedMD5,
+		    string ShortDesc, string ExpectedMD5,
 		    vector<DiffInfo> diffs=vector<DiffInfo>());
 };
 
-// Item class for index files
+/** \brief An acquire item that is responsible for fetching an index
+ *  file (e.g., Packages or Sources).
+ *
+ *  \sa pkgAcqDiffIndex, pkgAcqIndexDiffs, pkgAcqIndexTrans
+ *
+ *  \todo Why does pkgAcqIndex have protected members?
+ */
 class pkgAcqIndex : public pkgAcquire::Item
 {
    protected:
-   
+
+   /** \brief If \b true, the index file has been decompressed. */
    bool Decompression;
+
+   /** \brief If \b true, the partially downloaded file will be
+    *  removed when the download completes.
+    */
    bool Erase;
+
+   /** \brief The download request that is currently being
+    *   processed.
+    */
    pkgAcquire::ItemDesc Desc;
+
+   /** \brief The object that is actually being fetched (minus any
+    *  compression-related extensions).
+    */
    string RealURI;
+
+   /** \brief The expected md5sum of the decompressed index file. */
    string ExpectedMD5;
+
+   /** \brief The compression-related file extension that is being
+    *  added to the downloaded file (e.g., ".gz" or ".bz2").
+    */
    string CompressionExtension;
 
    public:
@@ -167,36 +522,120 @@ class pkgAcqIndex : public pkgAcquire::Item
    virtual string Custom600Headers();
    virtual string DescURI() {return RealURI + CompressionExtension;};
 
+   /** \brief Create a pkgAcqIndex.
+    *
+    *  \param Owner The pkgAcquire object with which this item is
+    *  associated.
+    *
+    *  \param URI The URI of the index file that is to be downloaded.
+    *
+    *  \param URIDesc A "URI-style" description of this index file.
+    *
+    *  \param ShortDesc A brief description of this index file.
+    *
+    *  \param ExpectedMD5 The expected md5sum of this index file.
+    *
+    *  \param compressExt The compression-related extension with which
+    *  this index file should be downloaded, or "" to autodetect
+    *  (".bz2" is used if bzip2 is installed, ".gz" otherwise).
+    */
    pkgAcqIndex(pkgAcquire *Owner,string URI,string URIDesc,
-	       string ShortDesct, string ExpectedMD5, string compressExt="");
+	       string ShortDesc, string ExpectedMD5, string compressExt="");
 };
 
-// Item class for translated package index files
+/** \brief An acquire item that is responsible for fetching a
+ *  translated index file.
+ *
+ *  The only difference from pkgAcqIndex is that transient failures
+ *  are suppressed: no error occurs if the translated index file is
+ *  missing.
+ */
 class pkgAcqIndexTrans : public pkgAcqIndex
 {
    public:
   
    virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
+
+   /** \brief Create a pkgAcqIndexTrans.
+    *
+    *  \param Owner The pkgAcquire object with which this item is
+    *  associated.
+    *
+    *  \param URI The URI of the index file that is to be downloaded.
+    *
+    *  \param URIDesc A "URI-style" description of this index file.
+    *
+    *  \param ShortDesc A brief description of this index file.
+    *
+    *  \param ExpectedMD5 The expected md5sum of this index file.
+    *
+    *  \param compressExt The compression-related extension with which
+    *  this index file should be downloaded, or "" to autodetect
+    *  (".bz2" is used if bzip2 is installed, ".gz" otherwise).
+    */
    pkgAcqIndexTrans(pkgAcquire *Owner,string URI,string URIDesc,
-		    string ShortDesct);
+		    string ShortDesc);
 };
 
+/** \brief Information about an index file. */
 struct IndexTarget
 {
+   /** \brief A URI from which the index file can be downloaded. */
    string URI;
+
+   /** \brief A description of the index file. */
    string Description;
+
+   /** \brief A shorter description of the index file. */
    string ShortDesc;
+
+   /** \brief The key by which this index file should be
+    *  looked up within the meta signature file.
+    */
    string MetaKey;
 };
 
-// Item class for index signatures
+/** \brief An acquire item that downloads the detached signature
+ *  of a meta-index (Release) file, then queues up the release
+ *  file itself.
+ *
+ *  \todo Why protected members?
+ *
+ *  \sa pkgAcqMetaIndex
+ */
 class pkgAcqMetaSig : public pkgAcquire::Item
 {
    protected:
-   
+   /** \brief The fetch request that is currently being processed. */
    pkgAcquire::ItemDesc Desc;
-   string RealURI,MetaIndexURI,MetaIndexURIDesc,MetaIndexShortDesc;
+
+   /** \brief The URI of the signature file.  Unlike Desc.URI, this is
+    *  never modified; it is used to determine the file that is being
+    *  downloaded.
+    */
+   string RealURI;
+
+   /** \brief The URI of the meta-index file to be fetched after the signature. */
+   string MetaIndexURI;
+
+   /** \brief A "URI-style" description of the meta-index file to be
+    *  fetched after the signature.
+    */
+   string MetaIndexURIDesc;
+
+   /** \brief A brief description of the meta-index file to be fetched
+    *  after the signature.
+    */
+   string MetaIndexShortDesc;
+
+   /** \brief A package-system-specific parser for the meta-index file. */
    indexRecords* MetaIndexParser;
+
+   /** \brief The index files which should be looked up in the meta-index
+    *  and then downloaded.
+    *
+    *  \todo Why a list of pointers instead of a list of structs?
+    */
    const vector<struct IndexTarget*>* IndexTargets;
 
    public:
@@ -208,27 +647,88 @@ class pkgAcqMetaSig : public pkgAcquire::Item
    virtual string Custom600Headers();
    virtual string DescURI() {return RealURI; };
 
+   /** \brief Create a new pkgAcqMetaSig. */
    pkgAcqMetaSig(pkgAcquire *Owner,string URI,string URIDesc, string ShortDesc,
 		 string MetaIndexURI, string MetaIndexURIDesc, string MetaIndexShortDesc,
 		 const vector<struct IndexTarget*>* IndexTargets,
 		 indexRecords* MetaIndexParser);
 };
 
-// Item class for index signatures
+/** \brief An item that is responsible for downloading the meta-index
+ *  file (i.e., Release) itself and verifying its signature.
+ *
+ *  Once the download and verification are complete, the downloads of
+ *  the individual index files are queued up using pkgAcqDiffIndex.
+ *  If the meta-index file had a valid signature, the expected md5sums
+ *  of the index files will be the md5sums listed in the meta-index;
+ *  otherwise, the expected md5sums will be "" (causing the
+ *  authentication of the index files to be bypassed).
+ */
 class pkgAcqMetaIndex : public pkgAcquire::Item
 {
    protected:
-   
+   /** \brief The fetch command that is currently being processed. */
    pkgAcquire::ItemDesc Desc;
-   string RealURI; // FIXME: is this redundant w/ Desc.URI?
+
+   /** \brief The URI that is actually being downloaded; never
+    *  modified by pkgAcqMetaIndex.
+    */
+   string RealURI;
+
+   /** \brief The file in which the signature for this index was stored.
+    *
+    *  If empty, the signature and the md5sums of the individual
+    *  indices will not be checked.
+    */
    string SigFile;
+
+   /** \brief The index files to download. */
    const vector<struct IndexTarget*>* IndexTargets;
+
+   /** \brief The parser for the meta-index file. */
    indexRecords* MetaIndexParser;
+
+   /** \brief If \b true, the index's signature is currently being verified.
+    */
    bool AuthPass;
 
+   /** \brief Check that the release file is a release file for the
+    *  correct distribution.
+    *
+    *  \return \b true if no fatal errors were encountered.
+    */
    bool VerifyVendor();
+
+   /** \brief Called when a file is finished being retrieved.
+    *
+    *  If the file was not downloaded to DestFile, a copy process is
+    *  set up to copy it to DestFile; otherwise, Complete is set to \b
+    *  true and the file is moved to its final location.
+    *
+    *  \param Message The message block received from the fetch
+    *  subprocess.
+    */
    void RetrievalDone(string Message);
+
+   /** \brief Called when authentication succeeded.
+    *
+    *  Sanity-checks the authenticated file, queues up the individual
+    *  index files for download, and saves the signature in the lists
+    *  directory next to the authenticated list file.
+    *
+    *  \param Message The message block received from the fetch
+    *  subprocess.
+    */
    void AuthDone(string Message);
+
+   /** \brief Starts downloading the individual index files.
+    *
+    *  \param verify If \b true, only indices whose expected md5sum
+    *  can be determined from the meta-index will be downloaded, and
+    *  the md5sums of indices will be checked (reporting
+    *  #StatAuthError if there is a mismatch).  If verify is \b false,
+    *  no md5sum checking will be performed.
+    */
    void QueueIndexes(bool verify);
    
    public:
@@ -240,6 +740,7 @@ class pkgAcqMetaIndex : public pkgAcquire::Item
    virtual string Custom600Headers();
    virtual string DescURI() {return RealURI; };
 
+   /** \brief Create a new pkgAcqMetaIndex. */
    pkgAcqMetaIndex(pkgAcquire *Owner,
 		   string URI,string URIDesc, string ShortDesc,
 		   string SigFile,
@@ -247,28 +748,58 @@ class pkgAcqMetaIndex : public pkgAcquire::Item
 		   indexRecords* MetaIndexParser);
 };
 
-// Item class for archive files
+/** \brief An item that is responsible for fetching a package file.
+ *
+ *  If the package file already exists in the cache, nothing will be
+ *  done.
+ */
 class pkgAcqArchive : public pkgAcquire::Item
 {
    protected:
-   
-   // State information for the retry mechanism
+   /** \brief The package version being fetched. */
    pkgCache::VerIterator Version;
+
+   /** \brief The fetch command that is currently being processed. */
    pkgAcquire::ItemDesc Desc;
+
+   /** \brief The list of sources from which to pick archives to
+    *  download this package from.
+    */
    pkgSourceList *Sources;
+
+   /** \brief A package records object, used to look up the file
+    *  corresponding to each version of the package.
+    */
    pkgRecords *Recs;
+
+   /** \brief The md5sum of this package. */
    string MD5;
+
+   /** \brief A location in which the actual filename of the package
+    *  should be stored.
+    */
    string &StoreFilename;
+
+   /** \brief The next file for this version to try to download. */
    pkgCache::VerFileIterator Vf;
+
+   /** \brief How many (more) times to try to find a new source from
+    *  which to download this package version if it fails.
+    *
+    *  Set from Acquire::Retries.
+    */
    unsigned int Retries;
+
+   /** \brief \b true if this version file is being downloaded from a
+    *  trusted source.
+    */
    bool Trusted; 
 
-   // Queue the next available file for download.
+   /** \brief Queue up the next available file for this version. */
    bool QueueNext();
    
    public:
    
-   // Specialized action members
    virtual void Failed(string Message,pkgAcquire::MethodConfig *Cnf);
    virtual void Done(string Message,unsigned long Size,string Md5Hash,
 		     pkgAcquire::MethodConfig *Cnf);
@@ -276,18 +807,49 @@ class pkgAcqArchive : public pkgAcquire::Item
    virtual string DescURI() {return Desc.URI;};
    virtual string ShortDesc() {return Desc.ShortDesc;};
    virtual void Finished();
+
    virtual bool IsTrusted();
    
+   /** \brief Create a new pkgAcqArchive.
+    *
+    *  \param Owner The pkgAcquire object with which this item is
+    *  associated.
+    *
+    *  \param Sources The sources from which to download version
+    *  files.
+    *
+    *  \param Recs A package records object, used to look up the file
+    *  corresponding to each version of the package.
+    *
+    *  \param Version The package version to download.
+    *
+    *  \param StoreFilename A location in which the actual filename of
+    *  the package should be stored.  It will be set to a guessed
+    *  basename in the constructor, and filled in with a fully
+    *  qualified filename once the download finishes.
+    */
    pkgAcqArchive(pkgAcquire *Owner,pkgSourceList *Sources,
 		 pkgRecords *Recs,pkgCache::VerIterator const &Version,
 		 string &StoreFilename);
 };
 
-// Fetch a generic file to the current directory
+/** \brief Retrieve an arbitrary file to the current directory.
+ *
+ *  The file is retrieved even if it is accessed via a URL type that
+ *  normally is a NOP, such as "file".  If the download fails, the
+ *  partial file is renamed to get a ".FAILED" extension.
+ */
 class pkgAcqFile : public pkgAcquire::Item
 {
+   /** \brief The currently active download process. */
    pkgAcquire::ItemDesc Desc;
+
+   /** \brief The md5sum of the file to download, if it is known. */
    string Md5Hash;
+
+   /** \brief How many times to retry the download, set from
+    *  Acquire::Retries.
+    */
    unsigned int Retries;
    
    public:
@@ -298,9 +860,29 @@ class pkgAcqFile : public pkgAcquire::Item
 		     pkgAcquire::MethodConfig *Cnf);
    virtual string MD5Sum() {return Md5Hash;};
    virtual string DescURI() {return Desc.URI;};
-   
+
+   /** \brief Create a new pkgAcqFile object.
+    *
+    *  \param Owner The pkgAcquire object with which this object is
+    *  associated.
+    *
+    *  \param URI The URI to download.
+    *
+    *  \param MD5 The md5sum of the file to download, if it is known;
+    *  otherwise "".
+    *
+    *  \param Size The size of the file to download, if it is known;
+    *  otherwise 0.
+    *
+    *  \param Desc A description of the file being downloaded.
+    *
+    *  \param ShortDesc A brief description of the file being
+    *  downloaded.
+    */
    pkgAcqFile(pkgAcquire *Owner,string URI,string MD5,unsigned long Size,
 		  string Desc,string ShortDesc);
 };
 
+/** @} */
+
 #endif
diff --git a/apt-pkg/acquire-method.h b/apt-pkg/acquire-method.h
index f46209d12..4f08a43ae 100644
--- a/apt-pkg/acquire-method.h
+++ b/apt-pkg/acquire-method.h
@@ -10,6 +10,13 @@
    
    ##################################################################### */
 									/*}}}*/
+
+/** \addtogroup acquire
+ *  @{
+ *
+ *  \file acquire-method.h
+ */
+
 #ifndef PKGLIB_ACQUIRE_METHOD_H
 #define PKGLIB_ACQUIRE_METHOD_H
 
@@ -86,4 +93,6 @@ class pkgAcqMethod
    virtual ~pkgAcqMethod() {};
 };
 
+/** @} */
+
 #endif
diff --git a/apt-pkg/acquire-worker.h b/apt-pkg/acquire-worker.h
index 6e1952202..1f6bcc05f 100644
--- a/apt-pkg/acquire-worker.h
+++ b/apt-pkg/acquire-worker.h
@@ -9,6 +9,13 @@
    
    ##################################################################### */
 									/*}}}*/
+
+/** \addtogroup acquire
+ *  @{
+ *
+ *  \file acquire-worker.h
+ */
+
 #ifndef PKGLIB_ACQUIRE_WORKER_H
 #define PKGLIB_ACQUIRE_WORKER_H
 
@@ -18,7 +25,25 @@
 #pragma interface "apt-pkg/acquire-worker.h"
 #endif 
 
-// Interfacing to the method process
+/** \brief A fetch subprocess.
+ *
+ *  A worker process is responsible for one stage of the fetch.  This
+ *  class encapsulates the communications protocol between the master
+ *  process and the worker, from the master end.
+ *
+ *  Each worker is intrinsically placed on two linked lists.  The
+ *  Queue list (maintained in the #NextQueue variable) is maintained
+ *  by the pkgAcquire::Queue class; it represents the set of workers
+ *  assigned to a particular queue.  The Acquire list (maintained in
+ *  the #NextAcquire variable) is maintained by the pkgAcquire class;
+ *  it represents the set of active workers for a particular
+ *  pkgAcquire object.
+ *
+ *  \todo Like everything else in the Acquire system, this has way too
+ *  many protected items.
+ *
+ *  \sa pkgAcqMethod, pkgAcquire::Item, pkgAcquire
+ */
 class pkgAcquire::Worker
 {
    friend class pkgAcquire;
@@ -26,64 +51,274 @@ class pkgAcquire::Worker
    protected:
    friend class Queue;
 
-   /* Linked list starting at a Queue and a linked list starting
-      at Acquire */
+   /** \brief The next link on the Queue list.
+    *
+    *  \todo This is always NULL; is it just for future use?
+    */
    Worker *NextQueue;
+
+   /** \brief The next link on the Acquire list. */
    Worker *NextAcquire;
    
-   // The access association
+   /** \brief The Queue with which this worker is associated. */
    Queue *OwnerQ;
+
+   /** \brief The download progress indicator to which progress
+    *  messages should be sent.
+    */
    pkgAcquireStatus *Log;
+
+   /** \brief The configuration of this method.  On startup, the
+    *  target of this pointer is filled in with basic data about the
+    *  method, as reported by the worker.
+    */
    MethodConfig *Config;
+
+   /** \brief The access method to be used by this worker.
+    *
+    *  \todo Doesn't this duplicate Config->Access?
+    */
    string Access;
 
-   // This is the subprocess IPC setup
+   /** \brief The PID of the subprocess. */
    pid_t Process;
+
+   /** \brief A file descriptor connected to the standard output of
+    *  the subprocess.
+    *
+    *  Used to read messages and data from the subprocess.
+    */
    int InFd;
+
+   /** \brief A file descriptor connected to the standard input of the
+    *  subprocess.
+    *
+    *  Used to send commands and configuration data to the subprocess.
+    */
    int OutFd;
+
+   /** \brief Set to \b true if the worker is in a state in which it
+    *  might generate data or command responses.
+    *
+    *  \todo Is this right?  It's a guess.
+    */
    bool InReady;
+
+   /** \brief Set to \b true if the worker is in a state in which it
+    *  is legal to send commands to it.
+    *
+    *  \todo Is this right?
+    */
    bool OutReady;
    
-   // Various internal things
+   /** If \b true, debugging output will be sent to std::clog. */
    bool Debug;
+
+   /** \brief The raw text values of messages received from the
+    *  worker, in sequence.
+    */
    vector<string> MessageQueue;
+
+   /** \brief Buffers pending writes to the subprocess.
+    *
+    *  \todo Wouldn't a std::dequeue be more appropriate?
+    */
    string OutQueue;
    
-   // Private constructor helper
+   /** \brief Common code for the constructor.
+    *
+    *  Initializes NextQueue and NextAcquire to NULL; Process, InFd,
+    *  and OutFd to -1, OutReady and InReady to \b false, and Debug
+    *  from _config.
+    */
    void Construct();
    
-   // Message handling things
+   /** \brief Retrieve any available messages from the subprocess.
+    *
+    *  The messages are retrieved as in ::ReadMessages(), and
+    *  MessageFailure() is invoked if an error occurs; in particular,
+    *  if the pipe to the subprocess dies unexpectedly while a message
+    *  is being read.
+    *
+    *  \return \b true if the messages were successfully read, \b
+    *  false otherwise.
+    */
    bool ReadMessages();
+
+   /** \brief Parse and dispatch pending messages.
+    *
+    *  This dispatches the message in a manner appropriate for its
+    *  type.
+    *
+    *  \todo Several message types lack separate handlers.
+    *
+    *  \sa Capabilities(), SendConfiguration(), MediaChange()
+    */
    bool RunMessages();
+
+   /** \brief Read and dispatch any pending messages from the
+    *  subprocess.
+    *
+    *  \return \b false if the subprocess died unexpectedly while a
+    *  message was being transmitted.
+    */
    bool InFdReady();
+
+   /** \brief Send any pending commands to the subprocess.
+    *
+    *  This method will fail if there is no pending output.
+    *
+    *  \return \b true if all commands were succeeded, \b false if an
+    *  error occurred (in which case MethodFailure() will be invoked).
+    */
    bool OutFdReady();
    
-   // The message handlers
+   /** \brief Handle a 100 Capabilities response from the subprocess.
+    *
+    *  \param Message the raw text of the message from the subprocess.
+    *
+    *  The message will be parsed and its contents used to fill
+    *  #Config.  If #Config is NULL, this routine is a NOP.
+    *
+    *  \return \b true.
+    */
    bool Capabilities(string Message);
+
+   /** \brief Send a 601 Configuration message (containing the APT
+    *  configuration) to the subprocess.
+    *
+    *  The APT configuration will be send to the subprocess in a
+    *  message of the following form:
+    *
+    *  <pre>
+    *  601 Configuration
+    *  Config-Item: Fully-Qualified-Item=Val
+    *  Config-Item: Fully-Qualified-Item=Val
+    *  ...
+    *  </pre>
+    *
+    *  \return \b true if the command was successfully sent, \b false
+    *  otherwise.
+    */
    bool SendConfiguration();
+
+   /** \brief Handle a 403 Media Change message.
+    *
+    *  \param Message the raw text of the message; the Media field
+    *  indicates what type of media should be changed, and the Drive
+    *  field indicates where the media is located.
+    *
+    *  Invokes pkgAcquireStatus::MediaChange(Media, Drive) to ask the
+    *  user to swap disks; informs the subprocess of the result (via
+    *  603 Media Changed, with the Failed field set to \b true if the
+    *  user cancelled the media change).
+    */
    bool MediaChange(string Message);
    
+   /** \brief Invoked when the worked process dies unexpectedly.
+    *
+    *  Waits for the subprocess to terminate and generates an error if
+    *  it terminated abnormally, then closes and blanks out all file
+    *  descriptors.  Discards all pending messages from the
+    *  subprocess.
+    *
+    *  \return \b false.
+    */
    bool MethodFailure();
+
+   /** \brief Invoked when a fetch job is completed, either
+    *  successfully or unsuccessfully.
+    *
+    *  Resets the status information for the worker process.
+    */
    void ItemDone();
    
    public:
    
-   // The curent method state
+   /** \brief The queue entry that is currently being downloaded. */
    pkgAcquire::Queue::QItem *CurrentItem;
+
+   /** \brief The most recent status string received from the
+    *  subprocess.
+    */
    string Status;
+
+   /** \brief How many bytes of the file have been downloaded.  Zero
+    *  if the current progress of the file cannot be determined.
+    */
    unsigned long CurrentSize;
+
+   /** \brief The total number of bytes to be downloaded.  Zero if the
+    *  total size of the final is unknown.
+    */
    unsigned long TotalSize;
+
+   /** \brief How much of the file was already downloaded prior to
+    *  starting this worker.
+    */
    unsigned long ResumePoint;
    
-   // Load the method and do the startup 
+   /** \brief Tell the subprocess to download the given item.
+    *
+    *  \param Item the item to queue up.
+    *  \return \b true if the item was successfully enqueued.
+    *
+    *  Queues up a 600 URI Acquire message for the given item to be
+    *  sent at the next possible moment.  Does \e not flush the output
+    *  queue.
+    */
    bool QueueItem(pkgAcquire::Queue::QItem *Item);
+
+   /** \brief Start up the worker and fill in #Config.
+    *
+    *  Reads the first message from the worker, which is assumed to be
+    *  a 100 Capabilities message.
+    *
+    *  \return \b true if all operations completed successfully.
+    */
    bool Start();
+
+   /** \brief Update the worker statistics (CurrentSize, TotalSize,
+    *  etc).
+    */
    void Pulse();
+
+   /** \return The fetch method configuration. */
    inline const MethodConfig *GetConf() const {return Config;};
-   
+
+   /** \brief Create a new Worker to download files.
+    *
+    *  \param OwnerQ The queue into which this worker should be
+    *  placed.
+    *
+    *  \param Config A location in which to store information about
+    *  the fetch method.
+    *
+    *  \param Log The download progress indicator that should be used
+    *  to report the progress of this worker.
+    */
    Worker(Queue *OwnerQ,MethodConfig *Config,pkgAcquireStatus *Log);
+
+   /** \brief Create a new Worker that should just retrieve
+    *  information about the fetch method.
+    *
+    *  Nothing in particular forces you to refrain from actually
+    *  downloading stuff, but the various status callbacks won't be
+    *  invoked.
+    *
+    *  \param Config A location in which to store information about
+    *  the fetch method.
+    */
    Worker(MethodConfig *Config);
+
+   /** \brief Clean up this worker.
+    *
+    *  Closes the file descriptors; if MethodConfig::NeedsCleanup is
+    *  \b false, also rudely interrupts the worker with a SIGINT.
+    */
    ~Worker();
 };
 
+/** @} */
+
 #endif
diff --git a/apt-pkg/acquire.h b/apt-pkg/acquire.h
index 27bb3d363..64dafdc9d 100644
--- a/apt-pkg/acquire.h
+++ b/apt-pkg/acquire.h
@@ -29,6 +29,40 @@
    
    ##################################################################### */
 									/*}}}*/
+
+/** \defgroup acquire Acquire system
+ *
+ *  \brief The Acquire system is responsible for retrieving files from
+ *  local or remote URIs and postprocessing them (for instance,
+ *  verifying their authenticity).  The core class in this system is
+ *  pkgAcquire, which is responsible for managing the download queues
+ *  during the download.  There is at least one download queue for
+ *  each supported protocol; protocols such as http may provide one
+ *  queue per host.
+ *
+ *  Each file to download is represented by a subclass of
+ *  pkgAcquire::Item.  The files add themselves to the download
+ *  queue(s) by providing their URI information to
+ *  pkgAcquire::Item::QueueURI, which calls pkgAcquire::Enqueue.
+ *
+ *  Once the system is set up, the Run method will spawn subprocesses
+ *  to handle the enqueued URIs; the scheduler will then take items
+ *  from the queues and feed them into the handlers until the queues
+ *  are empty.
+ *
+ *  \todo Acquire supports inserting an object into several queues at
+ *  once, but it is not clear what its behavior in this case is, and
+ *  no subclass of pkgAcquire::Item seems to actually use this
+ *  capability.
+ */
+
+/** \addtogroup acquire
+ *
+ *  @{
+ *
+ *  \file acquire.h
+ */
+
 #ifndef PKGLIB_ACQUIRE_H
 #define PKGLIB_ACQUIRE_H
 
@@ -46,6 +80,15 @@ using std::string;
 #include <unistd.h>
 
 class pkgAcquireStatus;
+
+/** \brief The core download scheduler.
+ *
+ *  This class represents an ongoing download.  It manages the lists
+ *  of active and pending downloads and handles setting up and tearing
+ *  down download-related structures.
+ *
+ *  \todo Why all the protected data items and methods?
+ */
 class pkgAcquire
 {   
    public:
@@ -60,97 +103,299 @@ class pkgAcquire
 
    typedef vector<Item *>::iterator ItemIterator;
    typedef vector<Item *>::const_iterator ItemCIterator;
-   
+
    protected:
    
-   // List of items to fetch
+   /** \brief A list of items to download.
+    *
+    *  This is built monotonically as items are created and only
+    *  emptied when the download shuts down.
+    */
    vector<Item *> Items;
    
-   // List of active queues and fetched method configuration parameters
+   /** \brief The head of the list of active queues.
+    *
+    *  \todo why a hand-managed list of queues instead of std::list or
+    *  std::set?
+    */
    Queue *Queues;
+
+   /** \brief The head of the list of active workers.
+    *
+    *  \todo why a hand-managed list of workers instead of std::list
+    *  or std::set?
+    */
    Worker *Workers;
+
+   /** \brief The head of the list of acquire method configurations.
+    *
+    *  Each protocol (http, ftp, gzip, etc) via which files can be
+    *  fetched can have a representation in this list.  The
+    *  configuration data is filled in by parsing the 100 Capabilities
+    *  string output by a method on startup (see
+    *  pkgAcqMethod::pkgAcqMethod and pkgAcquire::GetConfig).
+    *
+    *  \todo why a hand-managed config dictionary instead of std::map?
+    */
    MethodConfig *Configs;
+
+   /** \brief The progress indicator for this download. */
    pkgAcquireStatus *Log;
+
+   /** \brief The total size of the files which are to be fetched.
+    *
+    *  This is not necessarily the total number of bytes to download
+    *  when, e.g., download resumption and list updates via patches
+    *  are taken into account.
+    */
    unsigned long ToFetch;
 
-   // Configurable parameters for the schedular
-   enum {QueueHost,QueueAccess} QueueMode;
+   // Configurable parameters for the scheduler
+
+   /** \brief Represents the queuing strategy for remote URIs. */
+   enum QueueStrategy {
+     /** \brief Generate one queue for each protocol/host combination; downloads from 
+      *  multiple hosts can proceed in parallel.
+      */
+     QueueHost,
+     /** \brief Generate a single queue for each protocol; serialize
+      *  downloads from multiple hosts.
+      */
+     QueueAccess} QueueMode;
+
+   /** \brief If \b true, debugging information will be dumped to std::clog. */
    bool Debug;
+   /** \brief If \b true, a download is currently in progress. */
    bool Running;
-   
+
+   /** \brief Add the given item to the list of items. */
    void Add(Item *Item);
+
+   /** \brief Remove the given item from the list of items. */
    void Remove(Item *Item);
+
+   /** \brief Add the given worker to the list of workers. */
    void Add(Worker *Work);
+
+   /** \brief Remove the given worker from the list of workers. */
    void Remove(Worker *Work);
    
+   /** \brief Insert the given fetch request into the appropriate queue.
+    *
+    *  \param Item The URI to download and the item to download it
+    *  for.  Copied by value into the queue; no reference to Item is
+    *  retained.
+    */
    void Enqueue(ItemDesc &Item);
+
+   /** \brief Remove all fetch requests for this item from all queues. */
    void Dequeue(Item *Item);
+
+   /** \brief Determine the fetch method and queue of a URI.
+    *
+    *  \param URI The URI to fetch.
+    *
+    *  \param[out] Config A location in which to place the method via
+    *  which the URI is to be fetched.
+    *
+    *  \return the string-name of the queue in which a fetch request
+    *  for the given URI should be placed.
+    */
    string QueueName(string URI,MethodConfig const *&Config);
 
-   // FDSET managers for derived classes
+   /** \brief Build up the set of file descriptors upon which select() should
+    *  block.
+    *
+    *  The default implementation inserts the file descriptors
+    *  corresponding to active downloads.
+    *
+    *  \param[out] Fd The largest file descriptor in the generated sets.
+    *
+    *  \param[out] RSet The set of file descriptors that should be
+    *  watched for input.
+    *
+    *  \param[out] WSet The set of file descriptors that should be
+    *  watched for output.
+    */
    virtual void SetFds(int &Fd,fd_set *RSet,fd_set *WSet);
+
+   /** Handle input from and output to file descriptors which select()
+    *  has determined are ready.  The default implementation
+    *  dispatches to all active downloads.
+    *
+    *  \param RSet The set of file descriptors that are ready for
+    *  input.
+    *
+    *  \param WSet The set of file descriptors that are ready for
+    *  output.
+    */
    virtual void RunFds(fd_set *RSet,fd_set *WSet);   
 
-   // A queue calls this when it dequeues an item
+   /** \brief Check for idle queues with ready-to-fetch items.
+    *
+    *  Called by pkgAcquire::Queue::Done each time an item is dequeued
+    *  but remains on some queues; i.e., another queue should start
+    *  fetching it.
+    */
    void Bump();
    
    public:
 
+   /** \brief Retrieve information about a fetch method by name.
+    *
+    *  \param Access The name of the method to look up.
+    *
+    *  \return the method whose name is Access, or \b NULL if no such method exists.
+    */
    MethodConfig *GetConfig(string Access);
 
-   enum RunResult {Continue,Failed,Cancelled};
+   /** \brief Provides information on how a download terminated. */
+   enum RunResult {
+     /** \brief All files were fetched successfully. */
+     Continue,
+
+     /** \brief Some files failed to download. */
+     Failed,
+
+     /** \brief The download was cancelled by the user (i.e., #Log's
+      *  pkgAcquireStatus::Pulse() method returned \b false).
+      */
+     Cancelled};
 
-   RunResult Run(int PulseIntervall=500000);
+   /** \brief Download all the items that have been Add()ed to this
+    *  download process.
+    *
+    *  This method will block until the download completes, invoking
+    *  methods on #Log to report on the progress of the download.
+    *
+    *  \param PulseInterval The method pkgAcquireStatus::Pulse will be
+    *  invoked on #Log at intervals of PulseInterval milliseconds.
+    *
+    *  \return the result of the download.
+    */
+   RunResult Run(int PulseInterval=500000);
+
+   /** \brief Remove all items from this download process, terminate
+    *  all download workers, and empty all queues.
+    */
    void Shutdown();
    
-   // Simple iteration mechanism
+   /** \brief Get the first #Worker object.
+    *
+    *  \return the first active worker in this download process.
+    */
    inline Worker *WorkersBegin() {return Workers;};
+
+   /** \brief Advance to the next #Worker object.
+    *
+    *  \return the worker immediately following I, or \b NULL if none
+    *  exists.
+    */
    Worker *WorkerStep(Worker *I);
+
+   /** \brief Get the head of the list of items. */
    inline ItemIterator ItemsBegin() {return Items.begin();};
+
+   /** \brief Get the end iterator of the list of items. */
    inline ItemIterator ItemsEnd() {return Items.end();};
    
    // Iterate over queued Item URIs
    class UriIterator;
+   /** \brief Get the head of the list of enqueued item URIs.
+    *
+    *  This iterator will step over every element of every active
+    *  queue.
+    */
    UriIterator UriBegin();
+   /** \brief Get the end iterator of the list of enqueued item URIs. */
    UriIterator UriEnd();
    
-   // Cleans out the download dir
+   /** Deletes each entry in the given directory that is not being
+    *  downloaded by this object.  For instance, when downloading new
+    *  list files, calling Clean() will delete the old ones.
+    *
+    *  \param Dir The directory to be cleaned out.
+    *
+    *  \return \b true if the directory exists and is readable.
+    */
    bool Clean(string Dir);
 
-   // Returns the size of the total download set
+   /** \return the total size in bytes of all the items included in
+    *  this download.
+    */
    double TotalNeeded();
+
+   /** \return the size in bytes of all non-local items included in
+    *  this download.
+    */
    double FetchNeeded();
+
+   /** \return the amount of data to be fetched that is already
+    *  present on the filesystem.
+    */
    double PartialPresent();
 
+   /** \brief Construct a new pkgAcquire.
+    *
+    *  \param Log The progress indicator associated with this
+    *  download, or \b NULL for none.  This object is not owned by the
+    *  download process and will not be deleted when the pkgAcquire
+    *  object is destroyed.  Naturally, it should live for at least as
+    *  long as the pkgAcquire object does.
+    */
    pkgAcquire(pkgAcquireStatus *Log = 0);
+
+   /** \brief Destroy this pkgAcquire object.
+    *
+    *  Destroys all queue, method, and item objects associated with
+    *  this download.
+    */
    virtual ~pkgAcquire();
 };
 
-// Description of an Item+URI
+/** \brief Represents a single download source from which an item
+ *  should be downloaded.
+ *
+ *  An item may have several assocated ItemDescs over its lifetime.
+ */
 struct pkgAcquire::ItemDesc
 {
+   /** \brief The URI from which to download this item. */
    string URI;
+   /** brief A description of this item. */
    string Description;
+   /** brief A shorter description of this item. */
    string ShortDesc;
+   /** brief The underlying item which is to be downloaded. */
    Item *Owner;
 };
 
-// List of possible items queued for download.
+/** \brief A single download queue in a pkgAcquire object.
+ *
+ *  \todo Why so many protected values?
+ */
 class pkgAcquire::Queue
 {
    friend class pkgAcquire;
    friend class pkgAcquire::UriIterator;
    friend class pkgAcquire::Worker;
+
+   /** \brief The next queue in the pkgAcquire object's list of queues. */
    Queue *Next;
    
    protected:
 
-   // Queued item
+   /** \brief A single item placed in this queue. */
    struct QItem : pkgAcquire::ItemDesc
    {
-      QItem *Next;      
+      /** \brief The next item in the queue. */
+      QItem *Next;
+      /** \brief The worker associated with this item, if any. */
       pkgAcquire::Worker *Worker;
-      
+
+      /** \brief Assign the ItemDesc portion of this QItem from
+       *  another ItemDesc
+       */
       void operator =(pkgAcquire::ItemDesc const &I)
       {
 	 URI = I.URI;
@@ -160,45 +405,141 @@ class pkgAcquire::Queue
       };
    };
    
-   // Name of the queue
+   /** \brief The name of this queue. */
    string Name;
 
-   // Items queued into this queue
+   /** \brief The head of the list of items contained in this queue.
+    *
+    *  \todo why a by-hand list instead of an STL structure?
+    */
    QItem *Items;
+
+   /** \brief The head of the list of workers associated with this queue.
+    *
+    *  \todo This is plural because support exists in Queue for
+    *  multiple workers.  However, it does not appear that there is
+    *  any way to actually associate more than one worker with a
+    *  queue.
+    *
+    *  \todo Why not just use a std::set?
+    */
    pkgAcquire::Worker *Workers;
+
+   /** \brief the download scheduler with which this queue is associated. */
    pkgAcquire *Owner;
+
+   /** \brief The number of entries in this queue that are currently
+    *  being downloaded.
+    */
    signed long PipeDepth;
+
+   /** \brief The maximum number of entries that this queue will
+    *  attempt to download at once.
+    */
    unsigned long MaxPipeDepth;
    
    public:
    
-   // Put an item into this queue
+   /** \brief Insert the given fetch request into this queue. */
    void Enqueue(ItemDesc &Item);
+
+   /** \brief Remove all fetch requests for the given item from this queue.
+    *
+    *  \return \b true if at least one request was removed from the queue.
+    */
    bool Dequeue(Item *Owner);
 
-   // Find a Queued item
+   /** \brief Locate an item in this queue.
+    *
+    *  \param URI A URI to match against.
+    *  \param Owner A pkgAcquire::Worker to match against.
+    *
+    *  \return the first item in the queue whose URI is #URI and that
+    *  is being downloaded by #Owner.
+    */
    QItem *FindItem(string URI,pkgAcquire::Worker *Owner);
+
+   /** Presumably this should start downloading an item?
+    *
+    *  \todo Unimplemented.  Implement it or remove?
+    */
    bool ItemStart(QItem *Itm,unsigned long Size);
+
+   /** \brief Remove the given item from this queue and set its state
+    *  to pkgAcquire::Item::StatDone.
+    *
+    *  If this is the only queue containing the item, the item is also
+    *  removed from the main queue by calling pkgAcquire::Dequeue.
+    *
+    *  \param Itm The item to remove.
+    *
+    *  \return \b true if no errors are encountered.
+    */
    bool ItemDone(QItem *Itm);
    
+   /** \brief Start the worker process associated with this queue.
+    *
+    *  If a worker process is already associated with this queue,
+    *  this is equivalent to calling Cycle().
+    *
+    *  \return \b true if the startup was successful.
+    */
    bool Startup();
+
+   /** \brief Shut down the worker process associated with this queue.
+    *
+    *  \param Final If \b true, then the process is stopped unconditionally.
+    *               Otherwise, it is only stopped if it does not need cleanup
+    *               as indicated by the pkgAcqMethod::NeedsCleanup member of
+    *               its configuration.
+    *
+    *  \return \b true.
+    */
    bool Shutdown(bool Final);
+
+   /** \brief Send idle items to the worker process.
+    *
+    *  Fills up the pipeline by inserting idle items into the worker's queue.
+    */
    bool Cycle();
+
+   /** \brief Check for items that could be enqueued.
+    *
+    *  Call this after an item placed in multiple queues has gone from
+    *  the pkgAcquire::Item::StatFetching state to the
+    *  pkgAcquire::Item::StatIdle state, to possibly refill an empty queue.
+    *  This is an alias for Cycle().
+    *
+    *  \todo Why both this and Cycle()?  Are they expected to be
+    *  different someday?
+    */
    void Bump();
    
+   /** \brief Create a new Queue.
+    *
+    *  \param Name The name of the new queue.
+    *  \param Owner The download process that owns the new queue.
+    */
    Queue(string Name,pkgAcquire *Owner);
+
+   /** Shut down all the worker processes associated with this queue
+    *  and empty the queue.
+    */
    ~Queue();
 };
 
+/** \brief Iterates over all the URIs being fetched by a pkgAcquire object. */
 class pkgAcquire::UriIterator
 {
+   /** The next queue to iterate over. */
    pkgAcquire::Queue *CurQ;
+   /** The item that we currently point at. */
    pkgAcquire::Queue::QItem *CurItem;
    
    public:
    
-   // Advance to the next item
    inline void operator ++() {operator ++();};
+
    void operator ++(int)
    {
       CurItem = CurItem->Next;
@@ -209,11 +550,14 @@ class pkgAcquire::UriIterator
       }
    };
    
-   // Accessors
    inline pkgAcquire::ItemDesc const *operator ->() const {return CurItem;};
    inline bool operator !=(UriIterator const &rhs) const {return rhs.CurQ != CurQ || rhs.CurItem != CurItem;};
    inline bool operator ==(UriIterator const &rhs) const {return rhs.CurQ == CurQ && rhs.CurItem == CurItem;};
    
+   /** \brief Create a new UriIterator.
+    *
+    *  \param Q The queue over which this UriIterator should iterate.
+    */
    UriIterator(pkgAcquire::Queue *Q) : CurQ(Q), CurItem(0)
    {
       while (CurItem == 0 && CurQ != 0)
@@ -224,61 +568,200 @@ class pkgAcquire::UriIterator
    }   
 };
 
-// Configuration information from each method
+/** \brief Information about the properties of a single acquire method. */
 struct pkgAcquire::MethodConfig
 {
+   /** \brief The next link on the acquire method list.
+    *
+    *  \todo Why not an STL container?
+    */
    MethodConfig *Next;
    
+   /** \brief The name of this acquire method (e.g., http). */
    string Access;
 
+   /** \brief The implementation version of this acquire method. */
    string Version;
+
+   /** \brief If \b true, only one download queue should be created for this
+    *  method.
+    */
    bool SingleInstance;
+
+   /** \brief If \b true, this method supports pipelined downloading. */
    bool Pipeline;
+
+   /** \brief If \b true, the worker process should send the entire
+    *  APT configuration tree to the fetch subprocess when it starts
+    *  up.
+    */
    bool SendConfig;
+
+   /** \brief If \b true, this fetch method does not require network access;
+    *  all files are to be acquired from the local disk.
+    */
    bool LocalOnly;
+
+   /** \brief If \b true, the subprocess has to carry out some cleanup
+    *  actions before shutting down.
+    *
+    *  For instance, the cdrom method needs to unmount the CD after it
+    *  finishes.
+    */
    bool NeedsCleanup;
+
+   /** \brief If \b true, this fetch method acquires files from removable media. */
    bool Removable;
    
+   /** \brief Set up the default method parameters.
+    *
+    *  All fields are initialized to NULL, "", or \b false as
+    *  appropriate.
+    */
    MethodConfig();
 };
 
+/** \brief A monitor object for downloads controlled by the pkgAcquire class.
+ *
+ *  \todo Why protected members?
+ *
+ *  \todo Should the double members be uint64_t?
+ */
 class pkgAcquireStatus
 {
    protected:
    
+   /** \brief The last time at which this monitor object was updated. */
    struct timeval Time;
+
+   /** \brief The time at which the download started. */
    struct timeval StartTime;
+
+   /** \brief The number of bytes fetched as of the previous call to
+    *  pkgAcquireStatus::Pulse, including local items.
+    */
    double LastBytes;
+
+   /** \brief The current rate of download as of the most recent call
+    *  to pkgAcquireStatus::Pulse, in bytes per second.
+    */
    double CurrentCPS;
+
+   /** \brief The number of bytes fetched as of the most recent call
+    *  to pkgAcquireStatus::Pulse, including local items.
+    */
    double CurrentBytes;
+
+   /** \brief The total number of bytes that need to be fetched.
+    *
+    *  \warning This member is inaccurate, as new items might be
+    *  enqueued while the download is in progress!
+    */
    double TotalBytes;
+
+   /** \brief The total number of bytes accounted for by items that
+    *  were successfully fetched.
+    */
    double FetchedBytes;
+
+   /** \brief The amount of time that has elapsed since the download
+    *   started.
+    */
    unsigned long ElapsedTime;
+
+   /** \brief The total number of items that need to be fetched.
+    *
+    *  \warning This member is inaccurate, as new items might be
+    *  enqueued while the download is in progress!
+    */
    unsigned long TotalItems;
+
+   /** \brief The number of items that have been successfully downloaded. */
    unsigned long CurrentItems;
    
    public:
 
+   /** \brief If \b true, the download scheduler should call Pulse()
+    *  at the next available opportunity.
+    */
    bool Update;
+
+   /** \brief If \b true, extra Pulse() invocations will be performed.
+    *
+    *  With this option set, Pulse() will be called every time that a
+    *  download item starts downloading, finishes downloading, or
+    *  terminates with an error.
+    */
    bool MorePulses;
       
-   // Called by items when they have finished a real download
+   /** \brief Invoked when a local or remote file has been completely fetched.
+    *
+    *  \param Size The size of the file fetched.
+    *
+    *  \param ResumePoint How much of the file was already fetched.
+    */
    virtual void Fetched(unsigned long Size,unsigned long ResumePoint);
    
-   // Called to change media
+   /** \brief Invoked when the user should be prompted to change the
+    *         inserted removable media.
+    *
+    *  This method should not return until the user has confirmed to
+    *  the user interface that the media change is complete.
+    *
+    *  \param Media The name of the media type that should be changed.
+    *
+    *  \param Drive The identifying name of the drive whose media
+    *               should be changed.
+    *
+    *  \return \b true if the user confirms the media change, \b
+    *  false if it is cancelled.
+    *
+    *  \todo This is a horrible blocking monster; it should be CPSed
+    *  with prejudice.
+    */
    virtual bool MediaChange(string Media,string Drive) = 0;
    
-   // Each of these is called by the workers when an event occures
+   /** \brief Invoked when an item is confirmed to be up-to-date.
+
+    * For instance, when an HTTP download is informed that the file on
+    * the server was not modified.
+    */
    virtual void IMSHit(pkgAcquire::ItemDesc &/*Itm*/) {};
+
+   /** \brief Invoked when some of an item's data is fetched. */
    virtual void Fetch(pkgAcquire::ItemDesc &/*Itm*/) {};
+
+   /** \brief Invoked when an item is successfully and completely fetched. */
    virtual void Done(pkgAcquire::ItemDesc &/*Itm*/) {};
+
+   /** \brief Invoked when the process of fetching an item encounters
+    *  a fatal error.
+    */
    virtual void Fail(pkgAcquire::ItemDesc &/*Itm*/) {};
-   virtual bool Pulse(pkgAcquire *Owner); // returns false on user cancel
+
+   /** \brief Periodically invoked while the Acquire process is underway.
+    *
+    *  Subclasses should first call pkgAcquireStatus::Pulse(), then
+    *  update their status output.  The download process is blocked
+    *  while Pulse() is being called.
+    *
+    *  \return \b false if the user asked to cancel the whole Acquire process.
+    *
+    *  \see pkgAcquire::Run
+    */
+   virtual bool Pulse(pkgAcquire *Owner);
+
+   /** \brief Invoked when the Acquire process starts running. */
    virtual void Start();
+
+   /** \brief Invoked when the Acquire process stops running. */
    virtual void Stop();
    
+   /** \brief Initialize all counters to 0 and the time to the current time. */
    pkgAcquireStatus();
    virtual ~pkgAcquireStatus() {};
 };
 
+/** @} */
+
 #endif