* 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

1 files changed, 247 insertions, 12 deletions

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