Automated merge with file:///home/daniel/programming/aptitude/aptitude-gtk

105 files changed, 778 insertions, 298 deletions

diff --git a/src/apt_config_widgets.h b/src/apt_config_widgets.h
index a1e322da..a5b5fc63 100644
--- a/src/apt_config_widgets.h
+++ b/src/apt_config_widgets.h
@@ -17,12 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//  Classes that mediate between the configuration layer and the user
-//  interface layer.  Past versions of this file used multiple
-//  inheritance, but in order to handle memory management in an
-//  obvious and safe way, I modified this to explicitly make the
-//  UI-layer objects public members of the config-layer objects.  This
-//  is arguably cleaner anyway.
 
 #ifndef APT_CONFIG_WIDGETS_H
 #define APT_CONFIG_WIDGETS_H
@@ -36,6 +30,20 @@
 #include <string>
 #include <vector>
 
+/** \brief Classes that mediate between the configuration layer and the user
+ *  interface layer
+ *
+ * 
+ *  Classes that mediate between the configuration layer and the user
+ *  interface layer.  Past versions of this file used multiple
+ *  inheritance, but in order to handle memory management in an
+ *  obvious and safe way, I modified this to explicitly make the
+ *  UI-layer objects public members of the config-layer objects.  This
+ *  is arguably cleaner anyway.
+ * 
+ *  \file apt_config_widgets.h
+ */
+
 // This basically just provides a generic interface to commit changes
 // to apt options.
 class apt_config_widget : public sigc::trackable
diff --git a/src/apt_info_tree.h b/src/apt_info_tree.h
index b2d0347e..38c4b891 100644
--- a/src/apt_info_tree.h
+++ b/src/apt_info_tree.h
@@ -17,15 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//  Abstracts a tree which displays information about a particular package (and
-// optionally version).  The only thing that's special about this class is
-// that it can sanely restore its state after the apt cache has been flushed.
-//
-//  IMPORTANT NOTE: this assumes that simply deleting its root will be enough
-// to avoid segfaults while the cache is not valid.  Children that need more
-// assurances should connect to cache_closed themselves.  (FIXME: add a hook
-// in this class to avoid spiralling numbers of signal connections?  Good or bad
-// idea?)
 
 #ifndef APT_INFO_TREE_H
 #define APT_INFO_TREE_H
@@ -35,6 +26,22 @@
 #include <apt-pkg/pkgcache.h>
 #include <string>
 
+/** \brief Abstracts a tree which displays information about a particular package
+ *
+ * 
+ *  Abstracts a tree which displays information about a particular package (and
+ *  optionally version).  The only thing that's special about this class is
+ *  that it can sanely restore its state after the apt cache has been flushed.
+ *
+ *  IMPORTANT NOTE: this assumes that simply deleting its root will be enough
+ *  to avoid segfaults while the cache is not valid.  Children that need more
+ *  assurances should connect to cache_closed themselves.  (FIXME: add a hook
+ *  in this class to avoid spiralling numbers of signal connections?  Good or bad
+ *  idea?)
+ * 
+ *  \file apt_info_tree.h
+ */
+
 class apt_info_tree:public apt_undo_tree
 {
   std::string package, version;
diff --git a/src/apt_options.h b/src/apt_options.h
index 1898b3ec..7d528b3d 100644
--- a/src/apt_options.h
+++ b/src/apt_options.h
@@ -2,11 +2,15 @@
 //
 //  Copyright 2000 Daniel Burrows
 //
-//  The main options dialog
 
 #ifndef APT_OPTIONS_H
 #define APT_OPTIONS_H
 
+/** \brief The main options dialog
+ * 
+ *  \file apt_options.h
+ */
+
 namespace cwidget
 {
   namespace util
diff --git a/src/apt_undo_tree.h b/src/apt_undo_tree.h
index 737d464a..ba8e6cdb 100644
--- a/src/apt_undo_tree.h
+++ b/src/apt_undo_tree.h
@@ -17,14 +17,21 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Extends the basic menu_tree with support for the APT undo queue.
-// NB: this really ought to be a mixin for menu_redirect..
 
 #ifndef APT_UNDO_TREE_H
 #define APT_UNDO_TREE_H
 
 #include "menu_tree.h"
 
+/** \brief Extends the basic menu_tree with support for the APT undo queue
+ *
+ * 
+ *  Extends the basic menu_tree with support for the APT undo queue.
+ *  NB: this really ought to be a mixin for menu_redirect..
+ * 
+ *  \file apt_undo_tree.h
+ */
+
 class apt_undo_tree : public menu_tree
 {
 protected:
diff --git a/src/aptitude.h b/src/aptitude.h
index ea9ebe9d..9e66ac6e 100644
--- a/src/aptitude.h
+++ b/src/aptitude.h
@@ -3,7 +3,12 @@
 //  Copyright 2000 Masato Taruishi <taru@debian.org>,
 //                 Daniel Burrows <dburrows@debian.org>
 //
-//  common header
+
+/** \brief common header
+ *
+ * 
+ *  \file aptitude.h
+ */
 
 #ifndef APTITUDE_H
 #define APTITUDE_H
diff --git a/src/broken_indicator.h b/src/broken_indicator.h
index c4658443..fdb06308 100644
--- a/src/broken_indicator.h
+++ b/src/broken_indicator.h
@@ -17,12 +17,17 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Generates a (hopefully) unobtrusive hint about how to use the
-// problem resolver.
+
 
 #ifndef BROKEN_INDICATOR_H
 #define BROKEN_INDICATOR_H
 
+/** \brief Generates a (hopefully) unobtrusive hint about how to use the
+ *  problem resolver.
+ * 
+ *  \file broken_indicator.h
+ */
+
 namespace cwidget
 {
   namespace widgets
diff --git a/src/changelog_parse.h b/src/changelog_parse.h
index fc644fa6..011625d5 100644
--- a/src/changelog_parse.h
+++ b/src/changelog_parse.h
@@ -22,6 +22,9 @@
 
 #include <apt-pkg/pkgcache.h>
 
+/** \file changelog_parse.h
+ */
+
 namespace cwidget
 {
   class fragment;
diff --git a/src/cmdline/cmdline_action.h b/src/cmdline/cmdline_action.h
index 3a4e3eb8..93744351 100644
--- a/src/cmdline/cmdline_action.h
+++ b/src/cmdline/cmdline_action.h
@@ -7,6 +7,9 @@
 
 #include "cmdline_common.h"
 
+/** \file cmdline_action.h
+ */
+
 class pkgPolicy;
 
 /// \todo The command-line state should probably be encapsulated
diff --git a/src/cmdline/cmdline_changelog.h b/src/cmdline/cmdline_changelog.h
index a180a2a2..dcc35783 100644
--- a/src/cmdline/cmdline_changelog.h
+++ b/src/cmdline/cmdline_changelog.h
@@ -8,6 +8,9 @@
 #include <string>
 #include <vector>
 
+/** \file cmdline_changelog.h
+ */
+
 /** \brief Display the changelog of each of the given package specifiers.
  *
  *  The specifiers are literal package names, with optional version/archive
diff --git a/src/cmdline/cmdline_check_resolver.h b/src/cmdline/cmdline_check_resolver.h
index 67b69168..dfc83f25 100644
--- a/src/cmdline/cmdline_check_resolver.h
+++ b/src/cmdline/cmdline_check_resolver.h
@@ -20,6 +20,9 @@
 #ifndef CMDLINE_CHECK_RESOLVER
 #define CMDLINE_CHECK_RESOLVER
 
+/** \file cmdline_check_resolver.h
+ */
+
 int cmdline_check_resolver(int argc, char *argv[], const char *status_fname);
 
 #endif
diff --git a/src/cmdline/cmdline_clean.h b/src/cmdline/cmdline_clean.h
index 59d9fbe6..2fc854bb 100644
--- a/src/cmdline/cmdline_clean.h
+++ b/src/cmdline/cmdline_clean.h
@@ -5,6 +5,9 @@
 #ifndef CMDLINE_CLEAN_H
 #define CMDLINE_CLEAN_H
 
+/** \file cmdline_clean.h
+ */
+
 int cmdline_clean(int argc, char *argv[], bool simulate);
 int cmdline_autoclean(int argc, char *argv[], bool simulate);
 
diff --git a/src/cmdline/cmdline_common.h b/src/cmdline/cmdline_common.h
index 39a01a9b..fe5a7617 100644
--- a/src/cmdline/cmdline_common.h
+++ b/src/cmdline/cmdline_common.h
@@ -2,7 +2,6 @@
 //
 //   Copyright 2004 Daniel Burrows
 //
-// Stuff that doesn't particularly belong anywhere.
 
 #ifndef CMDLINE_COMMON_H
 #define CMDLINE_COMMON_H
@@ -13,6 +12,11 @@
 #include <string>
 #include <vector>
 
+/** \brief Stuff that doesn't particularly belong anywhere.
+ * 
+ *  \file cmdline_common.h
+ */
+
 extern int screen_width;
 void update_screen_width(int foo=0);
 
diff --git a/src/cmdline/cmdline_do_action.h b/src/cmdline/cmdline_do_action.h
index 4f2ba0ab..4d416dc8 100644
--- a/src/cmdline/cmdline_do_action.h
+++ b/src/cmdline/cmdline_do_action.h
@@ -7,6 +7,9 @@
 
 #include "cmdline_util.h"
 
+/** \file cmdline_do_action.h
+ */
+
 int cmdline_do_action(int argc, char *argv[],
 		      const char *status_fname, bool simulate,
 		      bool assume_yes, bool download_only, bool fix_broken,
diff --git a/src/cmdline/cmdline_download.h b/src/cmdline/cmdline_download.h
index addaf759..848fd395 100644
--- a/src/cmdline/cmdline_download.h
+++ b/src/cmdline/cmdline_download.h
@@ -5,6 +5,9 @@
 #ifndef CMDLINE_DOWNLOAD_H
 #define CMDLINE_DOWNLOAD_H
 
+/** \file cmdline_download.h
+ */
+
 int cmdline_download(int argc, char *argv[]);
 
 #endif // CMDLINE_DOWNLOAD_H
diff --git a/src/cmdline/cmdline_dump_resolver.h b/src/cmdline/cmdline_dump_resolver.h
index c8b0ec17..1cbf36bb 100644
--- a/src/cmdline/cmdline_dump_resolver.h
+++ b/src/cmdline/cmdline_dump_resolver.h
@@ -20,6 +20,9 @@
 #ifndef CMDLINE_DUMP_RESOLVER
 #define CMDLINE_DUMP_RESOLVER
 
+/** \file cmdline_dump_resolver.h
+ */
+
 int cmdline_dump_resolver(int argc, char *argv[], const char *status_fname);
 
 #endif
diff --git a/src/cmdline/cmdline_extract_cache_subset.h b/src/cmdline/cmdline_extract_cache_subset.h
index 87bce67a..52be4410 100644
--- a/src/cmdline/cmdline_extract_cache_subset.h
+++ b/src/cmdline/cmdline_extract_cache_subset.h
@@ -20,6 +20,9 @@
 #ifndef CMDLINE_EXTRACT_CACHE_SUBSET_H
 #define CMDLINE_EXTRACT_CACHE_SUBSET_H
 
+/** \file cmdline_extract_cache_subset.h
+ */
+
 namespace aptitude
 {
   namespace cmdline
diff --git a/src/cmdline/cmdline_forget_new.h b/src/cmdline/cmdline_forget_new.h
index 33ea888e..9c77d0d8 100644
--- a/src/cmdline/cmdline_forget_new.h
+++ b/src/cmdline/cmdline_forget_new.h
@@ -5,6 +5,9 @@
 #ifndef CMDLINE_FORGET_NEW_H
 #define CMDLINE_FORGET_NEW_H
 
+/** \file cmdline_forget_new.h
+ */
+
 int cmdline_forget_new(int argc, char *argv[],
 		       const char *status_fname, bool simulate);
 
diff --git a/src/cmdline/cmdline_moo.h b/src/cmdline/cmdline_moo.h
index 35c2259a..86e51a8a 100644
--- a/src/cmdline/cmdline_moo.h
+++ b/src/cmdline/cmdline_moo.h
@@ -2,11 +2,15 @@
 //
 //   Copyright 2004 Daniel Burrows
 //
-// The most important command-line action.
 
 #ifndef CMDLINE_MOO
 #define CMDLINE_MOO
 
+/** \brief The most important command-line action.
+ * 
+ *  \file cmdline_moo.h
+ */
+
 int cmdline_moo(int argc, char *argv[], int verbose);
 
 #endif // CMDLINE_MOO
diff --git a/src/cmdline/cmdline_progress.h b/src/cmdline/cmdline_progress.h
index 255bccee..14e2ffbf 100644
--- a/src/cmdline/cmdline_progress.h
+++ b/src/cmdline/cmdline_progress.h
@@ -5,6 +5,9 @@
 #ifndef CMDLINE_PROGRESS_H
 #define CMDLINE_PROGRESS_H
 
+/** \file cmdline_progress.h
+ */
+
 class download_signal_log;
 
 download_signal_log *gen_cmdline_download_progress();
diff --git a/src/cmdline/cmdline_prompt.h b/src/cmdline/cmdline_prompt.h
index f2015c7a..653e6d44 100644
--- a/src/cmdline/cmdline_prompt.h
+++ b/src/cmdline/cmdline_prompt.h
@@ -1,4 +1,4 @@
-// cmdline-prompt.h                     -*-c++-*-
+// cmdline_prompt.h                     -*-c++-*-
 //
 //  Copyright 2004 Daniel Burrows
 
@@ -9,6 +9,9 @@
 
 #include <cwidget/generic/util/exception.h>
 
+/** \file cmdline_prompt.h
+ */
+
 class pkgPolicy;
 
 /** Thrown when we get EOF on stdin.  Should never be thrown
diff --git a/src/cmdline/cmdline_resolver.h b/src/cmdline/cmdline_resolver.h
index 73136ed7..f320c129 100644
--- a/src/cmdline/cmdline_resolver.h
+++ b/src/cmdline/cmdline_resolver.h
@@ -25,6 +25,10 @@
 // We need these two to declare get_current_solution().
 //#include <generic/apt/aptitude_resolver_universe.h>
 #include <generic/problemresolver/solution.h>
+
+/** \file cmdline_resolver.h
+ */
+
 class aptitude_universe;
 
 class pkgPolicy;
diff --git a/src/cmdline/cmdline_search.h b/src/cmdline/cmdline_search.h
index 9154aeb7..ead96a70 100644
--- a/src/cmdline/cmdline_search.h
+++ b/src/cmdline/cmdline_search.h
@@ -7,6 +7,9 @@
 
 #include <string>
 
+/** \file cmdline_search.h
+ */
+
 int cmdline_search(int argc, char *argv[], const char *status_fname,
 		   std::string display_format, std::string width, std::string sort);
 
diff --git a/src/cmdline/cmdline_show.h b/src/cmdline/cmdline_show.h
index 45cc520e..f1cdd7a2 100644
--- a/src/cmdline/cmdline_show.h
+++ b/src/cmdline/cmdline_show.h
@@ -8,6 +8,9 @@
 #include <iosfwd>
 #include <string>
 
+/** \file cmdline_show.h
+ */
+
 namespace cwidget
 {
   class fragment_contents;
diff --git a/src/cmdline/cmdline_show_broken.h b/src/cmdline/cmdline_show_broken.h
index 2ffcb0cc..f371f2e1 100644
--- a/src/cmdline/cmdline_show_broken.h
+++ b/src/cmdline/cmdline_show_broken.h
@@ -5,6 +5,9 @@
 #ifndef CMDLINE_SHOW_BROKEN_H
 #define CMDLINE_SHOW_BROKEN_H
 
+/** \file cmdline_show_broken.h
+ */
+
 /** Shows a list of all broken packages together with their
  *  dependencies.  Similar to and based on the equivalent routine in
  *  apt-get.
diff --git a/src/cmdline/cmdline_simulate.h b/src/cmdline/cmdline_simulate.h
index 0431a360..545d3a7a 100644
--- a/src/cmdline/cmdline_simulate.h
+++ b/src/cmdline/cmdline_simulate.h
@@ -7,6 +7,9 @@
 
 #include "cmdline_common.h"
 
+/** \file cmdline_simulate.h
+ */
+
 class pkgPolicy;
 
 /** Simulate an install run.  to_install and friends are meant to be
diff --git a/src/cmdline/cmdline_spinner.h b/src/cmdline/cmdline_spinner.h
index 85589e61..ac512312 100644
--- a/src/cmdline/cmdline_spinner.h
+++ b/src/cmdline/cmdline_spinner.h
@@ -17,13 +17,17 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//  A generic spinner (for use with the background resolver).
 
 #ifndef CMDLINE_SPINNER_H
 #define CMDLINE_SPINNER_H
 
 #include <string>
 
+/** \brief A generic spinner (for use with the background resolver)
+ * 
+ *  \file cmdline_spinner.h
+ */
+
 /** A spinner for command-line output. */
 class cmdline_spinner
 {
diff --git a/src/cmdline/cmdline_update.h b/src/cmdline/cmdline_update.h
index 5a91f454..74beaab9 100644
--- a/src/cmdline/cmdline_update.h
+++ b/src/cmdline/cmdline_update.h
@@ -5,6 +5,9 @@
 #ifndef CMDLINE_UPDATE_H
 #define CMDLINE_UPDATE_H
 
+/** \file cmdline_update.h
+ */
+
 int cmdline_update(int argc, char *argv[], int verbose);
 
 #endif // CMDLINE_UPDATE_H
diff --git a/src/cmdline/cmdline_upgrade.h b/src/cmdline/cmdline_upgrade.h
index c541fb57..8b8bd6f4 100644
--- a/src/cmdline/cmdline_upgrade.h
+++ b/src/cmdline/cmdline_upgrade.h
@@ -9,6 +9,9 @@
 
 #include <vector>
 
+/** \file cmdline_upgrade.h
+ */
+
 int cmdline_upgrade(int argc, char *argv[],
 		    const char *status_fname, bool simulate,
 		    bool no_new_installs,
diff --git a/src/cmdline/cmdline_user_tag.h b/src/cmdline/cmdline_user_tag.h
index beaf7ce4..0f7fecf3 100644
--- a/src/cmdline/cmdline_user_tag.h
+++ b/src/cmdline/cmdline_user_tag.h
@@ -20,6 +20,9 @@
 #ifndef CMDLINE_USER_TAG_H
 #define CMDLINE_USER_TAG_H
 
+/** \file cmdline_user_tag.h
+ */
+
 namespace aptitude
 {
   namespace cmdline
diff --git a/src/cmdline/cmdline_util.h b/src/cmdline/cmdline_util.h
index 7fd824a4..d6bffeff 100644
--- a/src/cmdline/cmdline_util.h
+++ b/src/cmdline/cmdline_util.h
@@ -14,6 +14,9 @@
 
 #include <apt-pkg/srcrecords.h>
 
+/** \file cmdline_util.h
+ */
+
 void cmdline_show_pkglist(pkgvector &items);
 void cmdline_show_stringlist(strvector &items);
 
diff --git a/src/cmdline/cmdline_why.h b/src/cmdline/cmdline_why.h
index 90b1bb66..21c32be8 100644
--- a/src/cmdline/cmdline_why.h
+++ b/src/cmdline/cmdline_why.h
@@ -35,6 +35,9 @@
 
 #include <generic/util/immset.h>
 
+/** \file cmdline_why.h
+ */
+
 /** \brief Explain why a package is installed or conflicted against.
  *
  *  aptitude why A1 [A2 ...] B
diff --git a/src/cmdline_parse.h b/src/cmdline_parse.h
index 4a7cc53b..025b604b 100644
--- a/src/cmdline_parse.h
+++ b/src/cmdline_parse.h
@@ -2,9 +2,6 @@
 //
 //  Copyright 2002 Daniel Burrows
 //
-//  Mad?  They said I was mad.  But I didn't listen.  I didn't have to...
-//
-//  Behold...the living horror of the object-oriented command-line parser!
 
 #ifndef CMDLINE_PARSE_H
 #define CMDLINE_PARSE_H
@@ -14,6 +11,16 @@
 
 #include <sigc++/trackable.h>
 
+/** \brief A comand-line parser
+ *
+ * 
+ *  Mad?  They said I was mad.  But I didn't listen.  I didn't have to...
+ * 
+ *  Behold...the living horror of the object-oriented command-line parser!
+ * 
+ *  \file cmdline_parse.h
+ */
+
 // I'll parse arguments My Way, thank you.
 //
 // This provides a callback to parse the head of an input option stream.
diff --git a/src/defaults.h b/src/defaults.h
index fcfe2a03..9e5c831f 100644
--- a/src/defaults.h
+++ b/src/defaults.h
@@ -2,11 +2,15 @@
 //
 //  Copyright 1999 Daniel Burrows
 //
-//  Populates the Aptitude configuration with defaults for a bunch of stuff
 
 #ifndef DEFAULTS_H
 #define DEFAULT_H
 
+/** \brief Populates the Aptitude configuration with defaults for a bunch of stuff
+ * 
+ *  \file defaults.h
+ */
+
 void init_defaults();
 
 #endif
diff --git a/src/dep_item.h b/src/dep_item.h
index edfa6ee8..ecd252b2 100644
--- a/src/dep_item.h
+++ b/src/dep_item.h
@@ -17,7 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  An dependency chart for a package.
 
 #ifndef DEP_ITEM_H
 #define DEP_ITEM_H
@@ -30,6 +29,11 @@
 #include "pkg_subtree.h"
 #include "pkg_item_with_subtree.h"
 
+/** \brief A dependency chart for a package.
+ * 
+ *  \file dep_item.h
+ */
+
 // Inserts subtrees ("Depends", "Recommends", etc) for the package's
 // dependencies into the given tree.  You can template it to use either
 // pkg_tree or pkg_item_with_subtree.
diff --git a/src/desc_parse.h b/src/desc_parse.h
index e64ddccf..d2cdb07f 100644
--- a/src/desc_parse.h
+++ b/src/desc_parse.h
@@ -24,6 +24,9 @@
 
 #include <apt-pkg/pkgcache.h>
 
+/** \file desc_parse.h
+ */
+
 namespace cwidget
 {
   class fragment;
diff --git a/src/download_item.h b/src/download_item.h
index 773589e6..311f6cfc 100644
--- a/src/download_item.h
+++ b/src/download_item.h
@@ -17,7 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  This item represents something that's in a download queue.
 
 #ifndef DOWNLOAD_ITEM_H
 #define DOWNLOAD_ITEM_H
@@ -26,6 +25,11 @@
 
 #include <cwidget/widgets/treeitem.h>
 
+/** \brief This item represents something that's in a download queue
+ * 
+ *  \file download_item.h
+ */
+
 class download_item:public cwidget::widgets::treeitem
 {
   pkgAcquire::ItemDesc item;
diff --git a/src/download_list.h b/src/download_list.h
index 9ea7cf5b..0735d6b6 100644
--- a/src/download_list.h
+++ b/src/download_list.h
@@ -17,7 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//  A better download manager.  (..finally..)
 
 #ifndef DOWNLOAD_LIST_H
 #define DOWNLOAD_LIST_H
@@ -33,6 +32,14 @@
 
 #include <time.h>
 
+/** \brief A download manager
+ *
+ * 
+ *  A better download manager.  (..finally..)
+ * 
+ *  \file download_list.h
+ */
+
 class download_signal_log;
 
 class download_list:public cwidget::widgets::widget
diff --git a/src/download_thread.h b/src/download_thread.h
index 18d3e824..c539c03a 100644
--- a/src/download_thread.h
+++ b/src/download_thread.h
@@ -27,6 +27,9 @@
 
 #include <sigc++/slot.h>
 
+/** \file download_thread.h
+ */
+
 class download_manager;
 class download_signal_log;
 
diff --git a/src/edit_pkg_hier.h b/src/edit_pkg_hier.h
index e881eaa8..5e628d93 100644
--- a/src/edit_pkg_hier.h
+++ b/src/edit_pkg_hier.h
@@ -18,12 +18,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// This provides a convenient way to tweak the package hierarchy.  It lets
-// the user select which 'groups' a package appears in, then allows them to
-// save the changes to a file.
-//
-// Changes to the hierarchy are stored in GLOBAL VARIABLES.  Specifically,
-// the user_pkg_hier global variable.
 
 #ifndef EDIT_PKG_HIER
 #define EDIT_PKG_HIER
@@ -34,6 +28,19 @@
 
 #include <cwidget/widgets/tree.h>
 
+/** \brief Provides a convenient way to tweak the package hierarchy
+ *
+ * 
+ *  This provides a convenient way to tweak the package hierarchy.  It lets
+ *  the user select which 'groups' a package appears in, then allows them to
+ *  save the changes to a file.
+ *  
+ *  Changes to the hierarchy are stored in GLOBAL VARIABLES.  Specifically,
+ *  the user_pkg_hier global variable.
+ * 
+ *  \file edit_pkg_hier.h
+ */
+
 class hier_editor : public cwidget::widgets::tree
 {
   class hier_item;
diff --git a/src/generic/apt/acqprogress.h b/src/generic/apt/acqprogress.h
index b0ed2b3d..5130deb8 100644
--- a/src/generic/apt/acqprogress.h
+++ b/src/generic/apt/acqprogress.h
@@ -1,12 +1,8 @@
 // -*- mode: cpp; mode: fold -*-
 // Description								/*{{{*/
 // $Id: acqprogress.h,v 1.1.2.1 2002/02/23 14:50:07 daniel Exp $
-/* ######################################################################
-
-   Acquire Progress - Command line progress meter 
-   
-   ##################################################################### */
 									/*}}}*/
+
 #ifndef ACQPROGRESS_H
 #define ACQPROGRESS_H
 
@@ -14,6 +10,11 @@
 #include <sigc++/slot.h>
 #include <sigc++/trackable.h>
 
+/** \brief Acquire Progress - Command line progress meter
+ *
+ *  \file acqprogress.h
+ */
+
 class download_signal_log;
 
 class AcqTextStatus : public sigc::trackable
diff --git a/src/generic/apt/apt.h b/src/generic/apt/apt.h
index 9fa2509b..ce0e3550 100644
--- a/src/generic/apt/apt.h
+++ b/src/generic/apt/apt.h
@@ -17,10 +17,7 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  Argh.  It seems that it's pretty much necessary to have a central
-// repository for apt structures -- the cache in particular.  This is it.
-// No class wrapper because, well, the cache is already a class and you can't
-// open more than one at once, so there :)
+
 
 #ifndef APT_H
 #define APT_H
@@ -31,6 +28,17 @@
 
 #include <utility>
 
+/** \brief Central repository for apt structures
+ *
+ * 
+ *  Argh.  It seems that it's pretty much necessary to have a central
+ *  repository for apt structures -- the cache in particular.  This is it.
+ *  No class wrapper because, well, the cache is already a class and you can't
+ *  open more than one at once, so there :)
+ * 
+ *  \file apt.h
+ */
+
 class OpProgress;
 class pkgRecords;
 class pkgSourceList;
diff --git a/src/generic/apt/apt_undo_group.h b/src/generic/apt/apt_undo_group.h
index 6191bdb0..d3abdeaa 100644
--- a/src/generic/apt/apt_undo_group.h
+++ b/src/generic/apt/apt_undo_group.h
@@ -7,6 +7,9 @@
 
 #include <generic/util/undo.h>
 
+/** \file apt_undo_group.h
+ */
+
 /** An undo group that will call begin_action_group() and
  *  end_action_group() on the apt cache.  The apt cache is accessed
  *  via the global variable apt_cache_file.
diff --git a/src/generic/apt/aptcache.h b/src/generic/apt/aptcache.h
index 0ba79c4e..c8c541b7 100644
--- a/src/generic/apt/aptcache.h
+++ b/src/generic/apt/aptcache.h
@@ -1,13 +1,5 @@
 // aptcache.h  -*-c++-*-
 //
-//  Replacements for the Apt cache and dependency cache file classes.  Those
-// are lacking in a couple of crucial ways (eg: persistent state), so I
-// have to come up with my own set of routines.. :(
-//
-//  In order to track the appropriate package information, we must keep our
-// own file (I think..apt doesn't have hooks for adding stuff..) containing
-// that information, properly lock/unlock it, etc.
-//
 //  Copyright 1999-2005, 2007-2008 Daniel Burrows
 //
 //  This program is free software; you can redistribute it and/or modify
@@ -43,6 +35,20 @@
 #include <set>
 #include <vector>
 
+/** \brief Replacements for the Apt cache and dependency cache file classes
+ * 
+ * 
+ *  Replacements for the Apt cache and dependency cache file classes.  Those
+ *  are lacking in a couple of crucial ways (eg: persistent state), so I
+ *  have to come up with my own set of routines.. :(
+ *  
+ *  In order to track the appropriate package information, we must keep our
+ *  own file (I think..apt doesn't have hooks for adding stuff..) containing
+ *  that information, properly lock/unlock it, etc.
+ * 
+ * \file aptcache.h
+ */
+
 class undoable;
 class undo_group;
 class pkgProblemResolver;
diff --git a/src/generic/apt/aptitude_resolver.h b/src/generic/apt/aptitude_resolver.h
index 0310831f..3a9fb75e 100644
--- a/src/generic/apt/aptitude_resolver.h
+++ b/src/generic/apt/aptitude_resolver.h
@@ -18,21 +18,9 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Glue code to make the resolver talk to the core aptitude classes.
-//
-// shootshootshoot...maybe I should just teach the core about
-// conflicts...anyway, if not, then I need to be much more careful how
-// I iterate over conflicts if an OR is involved (it should be
-// basically ignored)
+// 
 //
-// General comment on how the iterators are handled: basically the
-// technique is (generally) to have a normalize() routine that
-// advances the current iterator(s) to the next "interesting"
-// iterator.  For instance, broken_dep_iterator::normalize() moves to
-// the next broken dependency (sort of).  If the current iterator is
-// already interesting, nothing happens.  This is used on
-// initialization and in operator++ (after advancing the iterator a
-// single step manually).
+
 
 #ifndef APTITUDE_RESOLVER_H
 #define APTITUDE_RESOLVER_H
@@ -43,6 +31,26 @@
 
 #include <generic/util/immset.h>
 
+/** \brief Glue code to make the resolver talk to the core aptitude classes.
+ *
+ * 
+ *  shootshootshoot...maybe I should just teach the core about
+ *  conflicts...anyway, if not, then I need to be much more careful how
+ *  I iterate over conflicts if an OR is involved (it should be
+ *  basically ignored)
+ *  
+ *  General comment on how the iterators are handled: basically the
+ *  technique is (generally) to have a normalize() routine that
+ *  advances the current iterator(s) to the next "interesting"
+ *  iterator.  For instance, broken_dep_iterator::normalize() moves to
+ *  the next broken dependency (sort of).  If the current iterator is
+ *  already interesting, nothing happens.  This is used on
+ *  initialization and in operator++ (after advancing the iterator a
+ *  single step manually).
+ * 
+ *  \file aptitude_resolver.h
+ */
+
 class aptitude_resolver:public generic_problem_resolver<aptitude_universe>
 {
   imm::map<package, action> keep_all_solution;
diff --git a/src/generic/apt/aptitude_resolver_universe.h b/src/generic/apt/aptitude_resolver_universe.h
index 53a3a645..cd1d35a8 100644
--- a/src/generic/apt/aptitude_resolver_universe.h
+++ b/src/generic/apt/aptitude_resolver_universe.h
@@ -29,6 +29,9 @@
 #include "apt.h"
 #include "aptcache.h"
 
+/** \file aptitude_resolver_universe.h
+ */
+
 class aptitude_resolver_version;
 
 /** \brief Translates an APT package into the abstract realm.
diff --git a/src/generic/apt/aptitudepolicy.h b/src/generic/apt/aptitudepolicy.h
index eb6e28ff..80c8cdc8 100644
--- a/src/generic/apt/aptitudepolicy.h
+++ b/src/generic/apt/aptitudepolicy.h
@@ -2,8 +2,6 @@
 //
 //  Copyright 2001 Daniel Burrows
 //
-//  A policy class that allows Recommends and Suggests to be treated as
-// "always important", "important for new installs", or "never important".
 
 #ifndef APTITUDEPOLICY_H
 #define APTITUDEPOLICY_H
@@ -14,6 +12,12 @@
 
 #include <apt-pkg/policy.h>
 
+/** \brief A policy class that allows Recommends and Suggests to be treated as
+ *  "always important", "important for new installs", or "never important".
+ * 
+ *  \file aptitudepolicy.h
+ */
+
 class aptitudePolicy:public pkgPolicy
 {
 public:
diff --git a/src/generic/apt/config_signal.h b/src/generic/apt/config_signal.h
index 8ed2ef78..d4b561ed 100644
--- a/src/generic/apt/config_signal.h
+++ b/src/generic/apt/config_signal.h
@@ -1,36 +1,6 @@
 // config_signal.h			-*-c++-*-
 //
-//  A framework for signals that are based on the apt configuration
-// code.  This uses a thin wrapper around the apt Configuration class.
-//
-//  This works in large part because apt-pkg itself does not (thankfully)
-// modify configuration items after it is initialized.
-//
-//  Important note: this configuration class supports "transparent themes".
-//  If PACKAGE::Theme is set, Find*(key) operations will look up key,
-// followed by PACKAGE::Themes::(PACKAGE::theme)::key.
-//
-//  This only breaks for things that use Tree -- which means that such code
-// might need to explicitly understand themes in order to work.  That is: if
-// it is appropriate for two disparate hierarchies to be "merged", you have to
-// do this on your own.  The default Tree call simply uses the theme as
-// a backing store.
-//
-//  IMPORTANT NOTE: setting values in the PACKAGE::Themes hierarchy will
-// not trigger signal emission on "shadowing" nodes!  Because themes are
-// expected to be static, I do not think this is a big deal, but you should
-// be aware of it.
-//
-//  MORE IMPORTANT NOTE: Altering the value of PACKAGE::Theme will
-// not trigger ANY signal emission right now.  (this *will* be a nuisance
-// and I hope to change it eventually)
-//
-//
-//
-//  In order to allow only non-default options to be saved, this does the
-// following (hack :P ) -- it stores TWO configuration dictionaries, updating
-// BOTH whenever an option is set, but only saving from the user's.  (in
-// fact, it uses three -- ouch!)
+
 
 #ifndef CONFIG_SIGNAL_H
 #define CONFIG_SIGNAL_H
@@ -49,6 +19,42 @@
 #include <map>
 #include <vector>
 
+/** \brief A framework for signals that are based on the apt configuration code.
+ *
+ * 
+ *  This uses a thin wrapper around the apt Configuration class.
+ *
+ *  This works in large part because apt-pkg itself does not (thankfully)
+ *  modify configuration items after it is initialized.
+ *  
+ *  Important note: this configuration class supports "transparent themes".
+ *  If PACKAGE::Theme is set, Find*(key) operations will look up key,
+ *  followed by PACKAGE::Themes::(PACKAGE::theme)::key.
+ *  
+ *  This only breaks for things that use Tree -- which means that such code
+ *  might need to explicitly understand themes in order to work.  That is: if
+ *  it is appropriate for two disparate hierarchies to be "merged", you have to
+ *  do this on your own.  The default Tree call simply uses the theme as
+ *  a backing store.
+ *  
+ *  IMPORTANT NOTE: setting values in the PACKAGE::Themes hierarchy will
+ *  not trigger signal emission on "shadowing" nodes!  Because themes are
+ *  expected to be static, I do not think this is a big deal, but you should
+ *  be aware of it.
+ *  
+ *  MORE IMPORTANT NOTE: Altering the value of PACKAGE::Theme will
+ *  not trigger ANY signal emission right now.  (this *will* be a nuisance
+ *  and I hope to change it eventually)
+ *  
+ *  
+ *  In order to allow only non-default options to be saved, this does the
+ *  following (hack :P ) -- it stores TWO configuration dictionaries, updating
+ *  BOTH whenever an option is set, but only saving from the user's.  (in
+ *  fact, it uses three -- ouch!)
+ * 
+ * \file config_signal.h
+ */
+
 class signalling_config:public sigc::trackable
 {
   Configuration *user_config, *system_config, *theme_config;
diff --git a/src/generic/apt/download_install_manager.h b/src/generic/apt/download_install_manager.h
index 3c1e84bb..a4d5f805 100644
--- a/src/generic/apt/download_install_manager.h
+++ b/src/generic/apt/download_install_manager.h
@@ -33,6 +33,9 @@
 #include <utility>
 #include <vector>
 
+/** \file download_install_manager.h
+ */
+
 /** Manages downloading and installing packages. */
 class download_install_manager : public download_manager
 {
diff --git a/src/generic/apt/download_manager.h b/src/generic/apt/download_manager.h
index 0d08b6f8..647ec0b3 100644
--- a/src/generic/apt/download_manager.h
+++ b/src/generic/apt/download_manager.h
@@ -17,8 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//  An abstract interface for download processes, and two
-//  implementations.
 
 #ifndef DOWNLOAD_MANAGER_H
 #define DOWNLOAD_MANAGER_H
@@ -28,6 +26,11 @@
 
 #include <sigc++/trackable.h>
 
+/** \brief An abstract interface for download processes, and two implementations.
+ *
+ *  \file download_manager.h
+ */ 
+
 class OpProgress;
 class download_signal_log;
 
diff --git a/src/generic/apt/download_signal_log.h b/src/generic/apt/download_signal_log.h
index 86945bfe..a48edff0 100644
--- a/src/generic/apt/download_signal_log.h
+++ b/src/generic/apt/download_signal_log.h
@@ -17,9 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//  A class that sits there emitting signals about the current
-// download status, and can be queried for specific info about that
-// status.
 
 #ifndef DOWNLOAD_SIGNAL_LOG_H
 #define DOWNLOAD_SIGNAL_LOG_H
@@ -31,6 +28,13 @@
 #include "aptitude.h"
 #include <cwidget/generic/util/ref_ptr.h>
 
+/** \brief A class that sits there emitting signals about the current
+ *  download status, and can be queried for specific info about that
+ *  status.
+ *
+ *  \file download_signal_log.h
+ */
+
 /** A download-signal log translates AcquireStatus calls into signals.
  *  Typically only one slot will be attached to each signal, but this
  *  allows a degree of separation to be introduced between the
diff --git a/src/generic/apt/download_update_manager.h b/src/generic/apt/download_update_manager.h
index 275d2e6e..7a3f4d1d 100644
--- a/src/generic/apt/download_update_manager.h
+++ b/src/generic/apt/download_update_manager.h
@@ -26,6 +26,9 @@
 
 #include <sigc++/signal.h>
 
+/** \file download_update_manager.h
+ */
+
 class download_signal_log;
 
 /** A class that handles updating the package lists. */
diff --git a/src/generic/apt/infer_reason.h b/src/generic/apt/infer_reason.h
index 1b4ed775..96f74b76 100644
--- a/src/generic/apt/infer_reason.h
+++ b/src/generic/apt/infer_reason.h
@@ -1,7 +1,5 @@
 // infer_reason.h
 //
-//  Code for inferring why a package is in its current state.
-//
 //  Copyright 2004 Daniel Burrows
 
 #ifndef INFER_DEPS_H
@@ -11,6 +9,11 @@
 
 #include <apt-pkg/pkgcache.h>
 
+/** \brief Code for inferring why a package is in its current state.
+ *
+ *  \file infer_reason.h
+ */
+
 /** A structure representing a package and a dependency of that
  *  package.  It is used below to return the reasons for a package's
  *  current state.
diff --git a/src/generic/apt/log.h b/src/generic/apt/log.h
index 89b2ae59..efa09597 100644
--- a/src/generic/apt/log.h
+++ b/src/generic/apt/log.h
@@ -17,11 +17,15 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//  A routine to write aptitude's automatic installation log.
 
 #ifndef LOG_H
 #define LOG_H
 
+/** \brief A routine to write aptitude's automatic installation log.
+ *
+ *  \file log.h
+ */
+
 /** Look up the log file's location in the apt configuration, and
  *  write a log stanza to it.
  */
diff --git a/src/generic/apt/matchers.h b/src/generic/apt/matchers.h
index 840ee452..d394ca83 100644
--- a/src/generic/apt/matchers.h
+++ b/src/generic/apt/matchers.h
@@ -17,8 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  Provides support for complex string-based matching of packages.  Patterns
-// can be compiled for later use or used and discarded.
 
 #ifndef MATCHERS_H
 #define MATCHERS_H
@@ -29,6 +27,15 @@
 
 #include <apt-pkg/pkgcache.h>
 
+/** \brief Provides support for complex string-based matching of packages
+ *
+ * 
+ *  Provides support for complex string-based matching of packages. Patterns
+ *  can be compiled for later use or used and discarded.
+ * 
+ *  \file matchers.h
+ */
+
 class aptitudeDepCache;
 class pkgRecords;
 
diff --git a/src/generic/apt/pkg_acqfile.h b/src/generic/apt/pkg_acqfile.h
index 14ceeac5..b3e6e7cc 100644
--- a/src/generic/apt/pkg_acqfile.h
+++ b/src/generic/apt/pkg_acqfile.h
@@ -19,6 +19,9 @@
 
 #include <apt-pkg/acquire-item.h>
 
+/** \file pkg_acqfile.h
+ */
+
 /** Like pkgAcqArchive, but uses generic File objects to download to
  *  the cwd (and copies from file:/ URLs).
  */
diff --git a/src/generic/apt/pkg_changelog.h b/src/generic/apt/pkg_changelog.h
index e700a8c8..d7552f30 100644
--- a/src/generic/apt/pkg_changelog.h
+++ b/src/generic/apt/pkg_changelog.h
@@ -17,7 +17,7 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  Routines to download a Debian changelog for a given package.
+
 
 #ifndef PKG_CHANGELOG_H
 #define PKG_CHANGELOG_H
@@ -30,6 +30,11 @@
 
 #include <sigc++/slot.h>
 
+/** \brief Routines to download a Debian changelog for a given package.
+ *
+ *  \file pkg_changelog.h
+ */
+
 class download_manager;
 
 /** Generate a download process object that retrieves the given
diff --git a/src/generic/apt/pkg_hier.h b/src/generic/apt/pkg_hier.h
index 4291e66d..4e5cf888 100644
--- a/src/generic/apt/pkg_hier.h
+++ b/src/generic/apt/pkg_hier.h
@@ -1,23 +1,8 @@
-// pkg-hier.h               -*-c++-*-
+// pkg_hier.h               -*-c++-*-
 //
 //  Copyright 2001 Daniel Burrows
 //
-//  This file allows a "package hierarchy" as described in README.hier to
-// be loaded and constructed.  Any number of files can be read into the
-// database; then, the database is "realized" as a tree using two virtual
-// callback routines.  (you should override them in a subclass to get
-// any specific behavior you need)
-//
-//  Important note: once you start "realizing" the database, adding new
-// nodes via input_file results in undefined behavior.
-//
-//  Second important note: Mixing top-down and bottom-up realization results
-// in undefined behavior.
-//
-//  With the bottom-up realization, the caller may manually set a "seen"
-// flag on a group to make it appear to be a "root".  (the caller should
-// also set the node_data values if this is doine)  Also, for root nodes,
-// realize_* will be called with a NULL parent_data argument.
+
 
 #ifndef PKG_HIER_H
 #define PKG_HIER_H
@@ -32,6 +17,30 @@
 #include <string>
 #include <vector>
 
+/** \brief This file allows a "package hierarchy" as described in README.hier to
+ *  be loaded and constructed.
+ *
+ * 
+ *  This file allows a "package hierarchy" as described in README.hier to
+ *  be loaded and constructed.  Any number of files can be read into the
+ *  database; then, the database is "realized" as a tree using two virtual
+ *  callback routines.  (you should override them in a subclass to get
+ *  any specific behavior you need)
+ *  
+ *  Important note: once you start "realizing" the database, adding new
+ *  nodes via input_file results in undefined behavior.
+ *  
+ *  Second important note: Mixing top-down and bottom-up realization results
+ *  in undefined behavior.
+ *  
+ *  With the bottom-up realization, the caller may manually set a "seen"
+ *  flag on a group to make it appear to be a "root".  (the caller should
+ *  also set the node_data values if this is doine)  Also, for root nodes,
+ *  realize_* will be called with a NULL parent_data argument.
+ * 
+ *  \file pkg_hier.h
+ */
+
 class pkg_hier
 {
 public:
diff --git a/src/generic/apt/resolver_manager.h b/src/generic/apt/resolver_manager.h
index b840fc00..09becf39 100644
--- a/src/generic/apt/resolver_manager.h
+++ b/src/generic/apt/resolver_manager.h
@@ -17,12 +17,7 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// A higher-level resolver interface.  This code is responsible for
-// maintaining a list of previously observed solutions, for passing
-// certain actions on to the underlying resolver (protecting users
-// from having to actually import the whole resolver definition), for
-// managing the resolver in the face of cache reloads and resets, and
-// for managing threaded access to the resolver.
+
 
 #ifndef RESOLVER_MANAGER_H
 #define RESOLVER_MANAGER_H
@@ -40,6 +35,19 @@
 #include <set>
 #include <vector>
 
+/** \brief A higher-level resolver interface
+ *
+ * 
+ *  A higher-level resolver interface. This code is responsible for
+ *  maintaining a list of previously observed solutions, for passing
+ *  certain actions on to the underlying resolver (protecting users
+ *  from having to actually import the whole resolver definition), for
+ *  managing the resolver in the face of cache reloads and resets, and
+ *  for managing threaded access to the resolver.
+ * 
+ *  \file resolver_manager.h
+ */
+
 class aptitude_universe;
 class aptitude_resolver_package;
 class aptitude_resolver_version;
diff --git a/src/generic/apt/rev_dep_iterator.h b/src/generic/apt/rev_dep_iterator.h
index 09bcd783..da0ba6d6 100644
--- a/src/generic/apt/rev_dep_iterator.h
+++ b/src/generic/apt/rev_dep_iterator.h
@@ -9,6 +9,9 @@
 
 #include "apt.h"
 
+/** \file rev_dep_iterator.h
+ */
+
 /** An iterator that iterates over all reverse deps of a package,
  *  including those that are via a Provided package.
  */
diff --git a/src/generic/apt/tags.h b/src/generic/apt/tags.h
index c8c83f15..2b8a36ed 100644
--- a/src/generic/apt/tags.h
+++ b/src/generic/apt/tags.h
@@ -17,7 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// A parser for tags.
 
 #ifndef TAGS_H
 #define TAGS_H
@@ -40,6 +39,11 @@
 
 #include <apt-pkg/pkgcache.h>
 
+/** \brief A parser for tags.
+ * 
+ *  \file tags.h
+ */
+
 class OpProgress;
 
 class tag
diff --git a/src/generic/apt/tasks.h b/src/generic/apt/tasks.h
index cfbcf8e1..813709bb 100644
--- a/src/generic/apt/tasks.h
+++ b/src/generic/apt/tasks.h
@@ -2,14 +2,18 @@
 //
 //  Copyright 2001 Daniel Burrows
 //
-//  Handles parsing the list of tasks and getting the task of a given
-// package.
 
 #include <string>
 #include <set>
 #include <map>
 #include <apt-pkg/pkgcache.h>
 
+/** \brief Handles parsing the list of tasks and getting the task of a given
+ *  package.
+ * 
+ *  \file tasks.h
+ */
+
 class OpProgress;
 
 class task
diff --git a/src/generic/problemresolver/dummy_universe.h b/src/generic/problemresolver/dummy_universe.h
index 8b2008e7..f15c74a7 100644
--- a/src/generic/problemresolver/dummy_universe.h
+++ b/src/generic/problemresolver/dummy_universe.h
@@ -17,8 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// A package dependency universe that's not terribly efficient, but
-// easy to set up for testing.
 
 #ifndef DUMMY_UNIVERSE_H
 #define DUMMY_UNIVERSE_H
@@ -32,6 +30,15 @@
 #include <cwidget/generic/util/eassert.h>
 #include <cwidget/generic/util/exception.h>
 
+/** \brief A package dependency universe
+ *
+ * 
+ *  A package dependency universe that's not terribly efficient, but
+ *  easy to set up for testing.
+ * 
+ *  \file dummy_universe.h
+ */
+
 // An error type that's thrown when a name lookup fails.
 class NoSuchNameError : public cwidget::util::Exception
 {
diff --git a/src/generic/problemresolver/dump_universe.h b/src/generic/problemresolver/dump_universe.h
index d0b8a4db..f2f7a7c4 100644
--- a/src/generic/problemresolver/dump_universe.h
+++ b/src/generic/problemresolver/dump_universe.h
@@ -22,6 +22,9 @@
 
 #include <iostream>
 
+/** \file dump_universe.h
+ */
+
 template<class PackageUniverse>
 void dump_universe(const PackageUniverse &world, std::ostream &out)
 {
diff --git a/src/generic/problemresolver/exceptions.h b/src/generic/problemresolver/exceptions.h
index e9fccd50..85ecff2b 100644
--- a/src/generic/problemresolver/exceptions.h
+++ b/src/generic/problemresolver/exceptions.h
@@ -22,6 +22,9 @@
 
 #include <cwidget/generic/util/exception.h>
 
+/** \file exceptions.h
+ */
+
 /** Generic errors in the problem resolver. */
 class ProblemResolverError : public cwidget::util::Exception {
 };
diff --git a/src/generic/problemresolver/problemresolver.h b/src/generic/problemresolver/problemresolver.h
index 0fb2bf22..2cb54a82 100644
--- a/src/generic/problemresolver/problemresolver.h
+++ b/src/generic/problemresolver/problemresolver.h
@@ -32,9 +32,6 @@
 //  Boston, MA 02111-1307, USA.
 //
 //
-// Generic problem resolver (generic because I want to be able to do
-// regression-testing for once, if I can figure out how, and Packages
-// files make lousy regression-tests).
 
 #ifndef PROBLEMRESOLVER_H
 #define PROBLEMRESOLVER_H
@@ -58,6 +55,16 @@
 
 #include <generic/util/dense_setset.h>
 
+/** \brief Generic problem resolver
+ *
+ * 
+ *  Generic problem resolver (generic because I want to be able to do
+ *  regression-testing for once, if I can figure out how, and Packages
+ *  files make lousy regression-tests).
+ * 
+ *  \file problemresolver.h
+ */
+
 template<typename Obj1, typename Obj2, typename Uni>
 inline void eassert_fail_on_2objs_soln(const std::string &file,
 				       size_t line,
diff --git a/src/generic/problemresolver/resolver_undo.h b/src/generic/problemresolver/resolver_undo.h
index 7e93ec57..520f825f 100644
--- a/src/generic/problemresolver/resolver_undo.h
+++ b/src/generic/problemresolver/resolver_undo.h
@@ -17,14 +17,21 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Undo items related to the resolver.  (Q: these could be unified
-// into a single item based on slots or somesuch?)
 
 #ifndef RESOLVER_UNDO_H
 #define RESOLVER_UNDO_H
 
 #include <generic/util/undo.h>
 
+/** \brief Undo items related to the resolver
+ *
+ * 
+ * Undo items related to the resolver.  (Q: these could be unified
+ * into a single item based on slots or somesuch?)
+ * 
+ *  \file resolver_undo.h
+ */
+
 template<typename PackageUniverse>
 class generic_problem_resolver;
 
diff --git a/src/generic/problemresolver/solution.h b/src/generic/problemresolver/solution.h
index 5b24f86f..4c1779ac 100644
--- a/src/generic/problemresolver/solution.h
+++ b/src/generic/problemresolver/solution.h
@@ -27,6 +27,11 @@
 
 #include <generic/util/immset.h>
 
+/** \brief The solution class for the problem resolver.
+ * 
+ *  \file solution.h
+ */
+
 template<typename PackageUniverse>
 class solution_weights;
 
diff --git a/src/generic/util/dense_setset.h b/src/generic/util/dense_setset.h
index d0b44697..c1fb231f 100644
--- a/src/generic/util/dense_setset.h
+++ b/src/generic/util/dense_setset.h
@@ -17,24 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Efficient representation of sets-of-sets and sets-of-maps which can
-// be indexed by a subset/superset relation.  In particular, given a
-// set of sets SS and a set T, provides the operation "is there an
-// element S' of SS such that each element of S' stands in a relation
-// R to an equivalent element of T" as well as its dual.  (with R
-// being the universal relation, this is just a straight subset
-// relation, but other general types of subsumption are also posible)
-//
-// WARNING: this class is completely non-threadsafe.  Because
-// find_subset is very heavily used (over a million calls in many test
-// cases), it has a number of optimizations, including one that means
-// YOU MAY NOT HAVE MULTIPLE SIMULTANEOUS CALLERS OF FIND_SUBSET as it
-// uses pre-allocated data structures to speed up its operation (by a
-// factor of 3 or so).
-
-// This is almost the same as setset, but optimized for the case where
-// the individual values are indexed by integers from 0 to N for some
-// N, and it's OK to allocate extra memory at creation time.
 
 #ifndef DENSE_SETSET_H
 #define DENSE_SETSET_H
@@ -47,6 +29,31 @@
 #include <vector>
 #include "immset.h"
 
+/** \brief Efficient representation of sets-of-sets and sets-of-maps
+ *
+ * 
+ *  Efficient representation of sets-of-sets and sets-of-maps which can
+ *  be indexed by a subset/superset relation.  In particular, given a
+ *  set of sets SS and a set T, provides the operation "is there an
+ *  element S' of SS such that each element of S' stands in a relation
+ *  R to an equivalent element of T" as well as its dual.  (with R
+ *  being the universal relation, this is just a straight subset
+ *  relation, but other general types of subsumption are also posible)
+ *  
+ *  WARNING: this class is completely non-threadsafe.  Because
+ *  find_subset is very heavily used (over a million calls in many test
+ *  cases), it has a number of optimizations, including one that means
+ *  YOU MAY NOT HAVE MULTIPLE SIMULTANEOUS CALLERS OF FIND_SUBSET as it
+ *  uses pre-allocated data structures to speed up its operation (by a
+ *  factor of 3 or so).
+ *  
+ *  This is almost the same as setset, but optimized for the case where
+ *  the individual values are indexed by integers from 0 to N for some
+ *  N, and it's OK to allocate extra memory at creation time.
+ * 
+ *  \file dense_setset.h
+ */
+
 /** Maintains a set of imm::sets of Val objects, arranged so that
  *  quick answers to the query "does the set S subsume any element of
  *  this set?" can be produced.  At the moment this object increases
diff --git a/src/generic/util/dirent_safe.h b/src/generic/util/dirent_safe.h
index 5c83c2c4..d7965541 100644
--- a/src/generic/util/dirent_safe.h
+++ b/src/generic/util/dirent_safe.h
@@ -22,6 +22,9 @@
 
 #include <dirent.h>
 
+/** \file dirent_safe.h
+ */
+
 /** \brief A version of dirent that's safe to use with readdir_r
  *  across platforms.
  *
diff --git a/src/generic/util/immset.h b/src/generic/util/immset.h
index 1bf82a1a..b5b6a844 100644
--- a/src/generic/util/immset.h
+++ b/src/generic/util/immset.h
@@ -17,18 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// This file defines a class to represent immutable sets.  These sets
-// behave like std::set, except that their contents cannot be changed;
-// they have no erase() or insert() operators, and only
-// const_iterators [0].  This restriction allows immutable sets to be
-// implemented in a way that makes both copying and creating a new set
-// by adding an element very efficient (O(1) and O(lg n) respectively;
-// with std::set these are both O(n)).
-//
-// [0] this refers to the wtree_node class; imm::set is a wrapper
-// around a wtree_node pointer that emulates a mutative interface by
-// creating a new tree and modifying its encapsulated pointer to point
-// there instead.
 
 #ifndef IMMSET_H
 #define IMMSET_H
@@ -38,6 +26,25 @@
 
 #include <vector>
 
+/** \brief A class to represent immutable sets
+ *
+ * 
+ *  This file defines a class to represent immutable sets.  These sets
+ *  behave like std::set, except that their contents cannot be changed;
+ *  they have no erase() or insert() operators, and only
+ *  const_iterators [0].  This restriction allows immutable sets to be
+ *  implemented in a way that makes both copying and creating a new set
+ *  by adding an element very efficient (O(1) and O(lg n) respectively;
+ *  with std::set these are both O(n)).
+ *  
+ *  [0] this refers to the wtree_node class; imm::set is a wrapper
+ *  around a wtree_node pointer that emulates a mutative interface by
+ *  creating a new tree and modifying its encapsulated pointer to point
+ *  there instead.
+ * 
+ *  \file immset.h
+ */
+
 namespace imm
 {
   /** A generic node in a weighted tree as described in "Implementing
diff --git a/src/generic/util/mut_fun.h b/src/generic/util/mut_fun.h
index 76793be7..9b8145ca 100644
--- a/src/generic/util/mut_fun.h
+++ b/src/generic/util/mut_fun.h
@@ -20,6 +20,9 @@
 #ifndef MUT_FUN_H
 #define MUT_FUN_H
 
+/** \file mut_fun.h
+ */
+
 /** A functor that assigns a value to a variable when it is
  *  triggered.
  */
diff --git a/src/generic/util/setset.h b/src/generic/util/setset.h
index 11d5d7c1..e447d6fe 100644
--- a/src/generic/util/setset.h
+++ b/src/generic/util/setset.h
@@ -17,20 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Efficient representation of sets-of-sets and sets-of-maps which can
-// be indexed by a subset/superset relation.  In particular, given a
-// set of sets SS and a set T, provides the operation "is there an
-// element S' of SS such that each element of S' stands in a relation
-// R to an equivalent element of T" as well as its dual.  (with R
-// being the universal relation, this is just a straight subset
-// relation, but other general types of subsumption are also posible)
-//
-// WARNING: this class is completely non-threadsafe.  Because
-// find_subset is very heavily used (over a million calls in many test
-// cases), it has a number of optimizations, including one that means
-// YOU MAY NOT HAVE MULTIPLE SIMULTANEOUS CALLERS OF FIND_SUBSET as it
-// uses pre-allocated data structures to speed up its operation (by a
-// factor of 3 or so).
 
 #ifndef SETSET_H
 #define SETSET_H
@@ -46,6 +32,27 @@
 
 #include <map>
 
+/** \brief Efficient representation of sets-of-sets and sets-of-maps
+ *
+ * 
+ *  Efficient representation of sets-of-sets and sets-of-maps which can
+ *  be indexed by a subset/superset relation.  In particular, given a
+ *  set of sets SS and a set T, provides the operation "is there an
+ *  element S' of SS such that each element of S' stands in a relation
+ *  R to an equivalent element of T" as well as its dual.  (with R
+ *  being the universal relation, this is just a straight subset
+ *  relation, but other general types of subsumption are also posible)
+ *  
+ *  WARNING: this class is completely non-threadsafe.  Because
+ *  find_subset is very heavily used (over a million calls in many test
+ *  cases), it has a number of optimizations, including one that means
+ *  YOU MAY NOT HAVE MULTIPLE SIMULTANEOUS CALLERS OF FIND_SUBSET as it
+ *  uses pre-allocated data structures to speed up its operation (by a
+ *  factor of 3 or so).
+ * 
+ *  \file setset.h
+ */
+
 /** Maintains a set of imm::sets of Val objects, arranged so that
  *  quick answers to the query "does the set S subsume any element of
  *  this set?" can be produced.  At the moment this object increases
diff --git a/src/generic/util/temp.h b/src/generic/util/temp.h
index 6f1d5199..4c3f482b 100644
--- a/src/generic/util/temp.h
+++ b/src/generic/util/temp.h
@@ -17,8 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Code to support safely creating files in a temporary directory and
-// deleting the directory when finished.
 
 #ifndef TEMP_H
 #define TEMP_H
@@ -29,6 +27,12 @@
 #include <cwidget/generic/util/exception.h>
 #include <cwidget/generic/threads/threads.h>
 
+/** \brief Code to support safely creating files in a temporary directory and
+ *  deleting the directory when finished.
+ * 
+ *  \file temp.h
+ */
+
 namespace temp
 {
   /** An exception thrown when a temporary object cannot be created. */
diff --git a/src/generic/util/undo.h b/src/generic/util/undo.h
index 9947e8ee..720a35ee 100644
--- a/src/generic/util/undo.h
+++ b/src/generic/util/undo.h
@@ -2,13 +2,18 @@
 //
 //  Copyright 2000 Daniel Burrows
 //
-//  A generic structure for undo information.
+//  
 
 #ifndef UNDO_H
 #define UNDO_H
 
 #include <list>
 
+/** \brief A generic structure for undo information.
+ * 
+ *  \file undo.h
+ */
+
 class undoable
 // represents an action which can be undone.
 {
diff --git a/src/generic/util/util.h b/src/generic/util/util.h
index f52950e6..ea66f7d5 100644
--- a/src/generic/util/util.h
+++ b/src/generic/util/util.h
@@ -24,6 +24,9 @@
 #include <utility>
 #include <vector>
 
+/** \file util.h
+ */
+
 struct tm;
 
 // Strip whitespace from the beginning and end of a string.
diff --git a/src/load_config.h b/src/load_config.h
index 721c44a4..e6162c2c 100644
--- a/src/load_config.h
+++ b/src/load_config.h
@@ -2,13 +2,17 @@
 //
 //  Copyright 2000 Daniel Burrows
 //
-//  Provides routines to load in the vscreen frontend's configuration.
 
 #ifndef LOAD_CONFIG_H
 #define LOAD_CONFIG_H
 
 #include <cwidget/config/keybindings.h>
 
+/** \brief Provides routines to load in the vscreen frontend's configuration.
+ * 
+ *  \file load_config.h
+ */
+
 void load_styles(std::string group, bool usetheme);
 //  Loads in color definitions from the given group.
 
diff --git a/src/load_grouppolicy.h b/src/load_grouppolicy.h
index 81951842..7afad0a9 100644
--- a/src/load_grouppolicy.h
+++ b/src/load_grouppolicy.h
@@ -2,26 +2,31 @@
 //
 //  Copyright 2001 Daniel Burrows
 //
-//  Routines to parse grouping policies.
-//
-// Grouping-policy configurations are written as follows:
-//
-// POLICY1,POLICY2(arg1,arg2,...,..,argN),POLICY3,...,POLICYN
-//
-// Each POLICY name specifies a way to sort at a particular level.  Obviously,
-// the policy names may not contain commas.  Similarly, arg1..argN are arguments
-// to the policies.  Different policies, just to be confusing, may implement
-// different handling of their arguments.
-//
-// If this ever gets totally out of control, it may be worthwhile to write a
-// routine allowing other modules to register parsers for an individual policy.
-// Right now I don't think this is necessary.
 
 #ifndef LOAD_GROUPPOLICY_H
 #define LOAD_GROUPPOLICY_H
 
 #include <string>
 
+/** \brief Routines to parse grouping policies.
+ *  
+ *  
+ *  Grouping-policy configurations are written as follows:
+ *  
+ *  POLICY1,POLICY2(arg1,arg2,...,..,argN),POLICY3,...,POLICYN
+ *  
+ *  Each POLICY name specifies a way to sort at a particular level.  Obviously,
+ *  the policy names may not contain commas.  Similarly, arg1..argN are arguments
+ *  to the policies.  Different policies, just to be confusing, may implement
+ *  different handling of their arguments.
+ *  
+ *  If this ever gets totally out of control, it may be worthwhile to write a
+ *  routine allowing other modules to register parsers for an individual policy.
+ *  Right now I don't think this is necessary.
+ * 
+ *  \file load_grouppolicy.h
+ */
+
 class pkg_grouppolicy_factory;
 
 pkg_grouppolicy_factory *parse_grouppolicy(std::string s);
diff --git a/src/load_pkgview.h b/src/load_pkgview.h
index 7f2fc12d..dbb16b7f 100644
--- a/src/load_pkgview.h
+++ b/src/load_pkgview.h
@@ -1,14 +1,22 @@
 // load_pkgview.h          -*-c++-*-
 //
-//  Lets a package-view layout be loaded from a config file.  It's not as
-// nice as it could be, but it's enough for real hardcore people like me to
-// customize things.
+
 
 #ifndef LOAD_PKGVIEW_H
 #define LOAD_PKGVIEW_H
 
 #include "pkg_view.h"
 
+/** \brief Lets a package-view layout be loaded from a config file
+ *
+ * 
+ *  Lets a package-view layout be loaded from a config file.  It's not as
+ *  nice as it could be, but it's enough for real hardcore people like me to
+ *  customize things.
+ * 
+ *  \file load_pkgview.h
+ */
+
 // The caller should delete the returned list, of course.
 std::list<package_view_item> *load_pkgview(std::string cfggroup);
 
diff --git a/src/load_sortpolicy.h b/src/load_sortpolicy.h
index fcb50306..32072dd0 100644
--- a/src/load_sortpolicy.h
+++ b/src/load_sortpolicy.h
@@ -7,6 +7,9 @@
 
 #include <string>
 
+/** \file load_sortpolicy.h
+ */
+
 class pkg_sortpolicy;
 
 pkg_sortpolicy *parse_sortpolicy(std::string s);
diff --git a/src/menu_redirect.h b/src/menu_redirect.h
index 3c216d82..54ba6f59 100644
--- a/src/menu_redirect.h
+++ b/src/menu_redirect.h
@@ -17,14 +17,21 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// This class allows some signals to be "redirected" from the menu to
-// appropriate widgets.
 
 #ifndef MENU_REDIRECT_H
 #define MENU_REDIRECT_H
 
 #include <sigc++/trackable.h>
 
+/** \brief Provides signal redirection from menu to widgets
+ *
+ * 
+ *  This class allows some signals to be "redirected" from the menu to
+ *  appropriate widgets.
+ * 
+ *  \file menu_redirect.h
+ */
+
 class menu_redirect:virtual public sigc::trackable
 {
 public:
diff --git a/src/menu_text_layout.h b/src/menu_text_layout.h
index 917aaf0b..abd3ce9d 100644
--- a/src/menu_text_layout.h
+++ b/src/menu_text_layout.h
@@ -25,6 +25,9 @@
 #include <cwidget/widgets/editline.h>
 #include <cwidget/widgets/text_layout.h>
 
+/** \file menu_text_layout.h
+ */
+
 class menu_text_layout : public cwidget::widgets::text_layout, public menu_redirect
 {
   std::wstring last_search;
diff --git a/src/menu_tree.h b/src/menu_tree.h
index 39b0a97b..1e7d22f1 100644
--- a/src/menu_tree.h
+++ b/src/menu_tree.h
@@ -17,7 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// A cwidget::widgets::tree augmented with the ability to act as a menu redirector.
 
 #ifndef MENU_TREE
 #define MENU_TREE
@@ -28,6 +27,11 @@
 
 #include <cwidget/widgets/tree.h>
 
+/** \brief A cwidget::widgets::tree augmented with the ability to act as a menu redirector.
+ * 
+ *  \file menu_tree.h
+ */
+
 namespace aptitude
 {
   namespace matching
diff --git a/src/mine/board.h b/src/mine/board.h
index 00d0ca7a..c59c4b32 100644
--- a/src/mine/board.h
+++ b/src/mine/board.h
@@ -2,8 +2,6 @@
 //
 //  Copyright 2000 Daniel Burrows
 //
-//  Contains the information and routines necessary to play a game of
-// minesweeper.
 
 #ifndef BOARD_H
 #define BOARD_H
@@ -13,6 +11,12 @@
 #include <cwidget/generic/util/eassert.h>
 #include <time.h>
 
+/** \brief Contains the information and routines necessary to play a game of
+ *  minesweeper
+ * 
+ *  \file board.h
+ */
+
 class mine_board
 // A 'dumb' class that just contains information necessary to manipulate the
 // game board.  Quick note: this doesn't contain any bounds-checking; the
diff --git a/src/mine/cmine.h b/src/mine/cmine.h
index 0f5682dc..3f47cce6 100644
--- a/src/mine/cmine.h
+++ b/src/mine/cmine.h
@@ -2,22 +2,6 @@
 //
 //  Copyright 2000 Daniel Burrows
 //
-//  A Curses interface to Minesweeper, using the vscreen architecture.  The
-// idea is that it'll be possible to drop this into a vscreen-using program
-// and have it Just Work.  Currently vscreen is (aside from the manually
-// extracted code in this tree) only used in aptitude, but if I ever get
-// around to breaking it into its own library, this'll be useful.  Also, as
-// Caldera demonstrated, playing games while your packages are downloading has
-// a high reading on the Cool Useless Feature Scale :-)
-//
-//  (that's also the reason that there's room made for some stuff that's not
-// really accessible from the version I'm turning in -- in particular,
-// configuration of colors and keybindings.  To make use of them you really
-// need a configuration file, and I don't want to write a parser here..aptitude
-// just piggybacks on the apt configuration, so I don't really have a parser
-// from that that I can borrow either..hmmm..I think the apt parser is
-// public-domain, but I'm not sure how that interacts with our collaboration
-// policy :) )
 
 #ifndef CMINE_H
 #define CMINE_H
@@ -27,6 +11,29 @@
 #include <cwidget/widgets/minibuf_win.h>
 #include <cwidget/widgets/editline.h>
 
+/** \brief A Curses interface to Minesweeper, using the vscreen architecture
+ * 
+ * 
+ *  A Curses interface to Minesweeper, using the vscreen architecture.  The
+ *  idea is that it'll be possible to drop this into a vscreen-using program
+ *  and have it Just Work.  Currently vscreen is (aside from the manually
+ *  extracted code in this tree) only used in aptitude, but if I ever get
+ *  around to breaking it into its own library, this'll be useful.  Also, as
+ *  Caldera demonstrated, playing games while your packages are downloading has
+ *  a high reading on the Cool Useless Feature Scale :-)
+ *  
+ *  (that's also the reason that there's room made for some stuff that's not
+ *  really accessible from the version I'm turning in -- in particular,
+ *  configuration of colors and keybindings.  To make use of them you really
+ *  need a configuration file, and I don't want to write a parser here..aptitude
+ *  just piggybacks on the apt configuration, so I don't really have a parser
+ *  from that that I can borrow either..hmmm..I think the apt parser is
+ *  public-domain, but I'm not sure how that interacts with our collaboration
+ *  policy :) )
+ * 
+ * \file cmine.h
+ */
+
 namespace cwidget
 {
   namespace widgets
diff --git a/src/pkg_columnizer.h b/src/pkg_columnizer.h
index 0a0f35e0..b676db10 100644
--- a/src/pkg_columnizer.h
+++ b/src/pkg_columnizer.h
@@ -17,8 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  The rather hefty pkg_columnizer class and associated data (eg, info about
-// column sizes) lives here.
 
 #ifndef PKG_COLUMNIZER_H
 #define PKG_COLUMNIZER_H
@@ -26,6 +24,15 @@
 #include "pkg_item.h"
 #include <cwidget/config/column_definition.h>
 
+/** \brief pkg_columnizer class and associated data
+ *
+ * 
+ *  The rather hefty pkg_columnizer class and associated data (eg, info about
+ *  column sizes) lives here.
+ * 
+ *  \file pkg_columnizer.h
+ */
+
 class pkg_item::pkg_columnizer : public cwidget::config::column_generator
 {
   class pkg_genheaders;
diff --git a/src/pkg_grouppolicy.h b/src/pkg_grouppolicy.h
index 0864eda8..055a743a 100644
--- a/src/pkg_grouppolicy.h
+++ b/src/pkg_grouppolicy.h
@@ -17,32 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  Ok, this requires (a little) explanation -- basically, the idea is that
-// we need a flexible way to group (and filter) packages.  These classes
-// provide that.  A grouping policy knows what tree it should add things to,
-// and can add subtrees or packages at its own discretion.  A policy
-// *factory* is used as a way to chain policies together -- rather than
-// directly adding packages to trees they create, most packages will
-// instantiate (using a factory) a policy for each subtree.
-//
-//  In other words: say we want to group by top-level section, then by
-// subsection.  We create a pkg_groupsectionpolicy_factory with the
-// proper arguments to group by top-level section, with its 'chain' argument
-// set to another pkg_groupsectionpolicy_factory (which, however, groups
-// by subsection) with its chain argument set to a pkg_grouppolicy_end_factory.
-//
-//  Note that the policy classes are not themselves visible to the user,
-// simply to avoid unnecessary recompiles.  The factories are the only way
-// to get a policy class.
-//
-//  The factories could probably be functions/function pointers as well,
-// but classes are more flexible in this instance.
-//
-//  Because of the way factories and policies generally work you should never
-// destroy a factory before destroying the new objects created by it.
-
-// An abstract base class for objects containing the logic to sort packages
-// into groups
 
 #ifndef PKG_GROUPPOLICY_H
 #define PKG_GROUPPOLICY_H
@@ -52,6 +26,39 @@
 
 #include <vector>
 
+/** \brief Provides a flexible way to group and filter packages
+ *
+ * 
+ *  Ok, this requires (a little) explanation -- basically, the idea is that
+ *  we need a flexible way to group (and filter) packages.  These classes
+ *  provide that.  A grouping policy knows what tree it should add things to,
+ *  and can add subtrees or packages at its own discretion.  A policy
+ *  *factory* is used as a way to chain policies together -- rather than
+ *  directly adding packages to trees they create, most packages will
+ *  instantiate (using a factory) a policy for each subtree.
+ *  
+ *  In other words: say we want to group by top-level section, then by
+ *  subsection.  We create a pkg_groupsectionpolicy_factory with the
+ *  proper arguments to group by top-level section, with its 'chain' argument
+ *  set to another pkg_groupsectionpolicy_factory (which, however, groups
+ *  by subsection) with its chain argument set to a pkg_grouppolicy_end_factory.
+ *  
+ *  Note that the policy classes are not themselves visible to the user,
+ *  simply to avoid unnecessary recompiles.  The factories are the only way
+ *  to get a policy class.
+ *  
+ *  The factories could probably be functions/function pointers as well,
+ *  but classes are more flexible in this instance.
+ *  
+ *  Because of the way factories and policies generally work you should never
+ *  destroy a factory before destroying the new objects created by it.
+ *  
+ *  An abstract base class for objects containing the logic to sort packages
+ *  into groups
+ * 
+ *  \file pkg_grouppolicy.h
+ */
+
 // Used to set the visible status if a package is available.
 typedef sigc::signal2<void,
 		      const pkgCache::PkgIterator &,
diff --git a/src/pkg_info_screen.h b/src/pkg_info_screen.h
index 218b306b..602ad922 100644
--- a/src/pkg_info_screen.h
+++ b/src/pkg_info_screen.h
@@ -17,9 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  Gathers information about a package into one
-// spot (pkg_grouppolicy_info_factory) and provides dedicated code to display
-// it (pkg_info_screen)
 
 #ifndef PKG_INFO_SCREEN_H
 #define PKG_INFO_SCREEN_H
@@ -31,6 +28,16 @@
 #include <apt-pkg/cacheiterators.h>
 #include <string>
 
+/** \brief Gathers package information and provides code to display it
+ *
+ * 
+ *  Gathers information about a package into one
+ *  spot (pkg_grouppolicy_info_factory) and provides dedicated code to display
+ *  it (pkg_info_screen)
+ * 
+ *  \file pkg_info_screen.h
+ */
+
 class pkg_grouppolicy_info_factory:public pkg_grouppolicy_factory
 {
 public:
diff --git a/src/pkg_item.h b/src/pkg_item.h
index 86a32870..5d99961a 100644
--- a/src/pkg_item.h
+++ b/src/pkg_item.h
@@ -17,7 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  A tree item which represents a package.
 
 #ifndef PKG_ITEM_H
 #define PKG_ITEM_H
@@ -28,6 +27,11 @@
 
 #include <sigc++/signal.h>
 
+/** \brief A tree item which represents a package
+ * 
+ *  \file pkg_item.h
+ */
+
 /** A tree item which represents a package. */
 class pkg_item:public pkg_tree_node
 {
diff --git a/src/pkg_item_with_subtree.h b/src/pkg_item_with_subtree.h
index 4b3fd407..94732da9 100644
--- a/src/pkg_item_with_subtree.h
+++ b/src/pkg_item_with_subtree.h
@@ -17,8 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  A package item with an associated subtree.  More useful than you might
-// think ;-)
 
 #ifndef PKG_ITEM_WITH_SUBTREE_H
 #define PKG_ITEM_WITH_SUBTREE_H
@@ -31,6 +29,15 @@
 #include <cwidget/generic/util/transcode.h>
 #include <cwidget/widgets/subtree.h>
 
+/** \brief A package item with an associated subtree
+ *
+ * 
+ *  A package item with an associated subtree.  More useful than you might
+ *  think ;-)
+ * 
+ *  \file pkg_item_with_subtree.h
+ */
+
 template<class child, class sorter = cwidget::widgets::tag_sort_policy>
 class pkg_item_with_subtree:public cwidget::widgets::subtree<child, sorter>, public pkg_item
 {
diff --git a/src/pkg_node.h b/src/pkg_node.h
index f2847bfc..3e807b65 100644
--- a/src/pkg_node.h
+++ b/src/pkg_node.h
@@ -17,8 +17,7 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  In the fine tradition of breaking header files up into their smallest
-// usable components..
+//  
 
 #ifndef PKG_NODE_H
 #define PKG_NODE_H
@@ -27,6 +26,15 @@
 
 #include <cwidget/widgets/treeitem.h>
 
+/** \brief Provides nodes related actions
+ *
+ * 
+ *  In the fine tradition of breaking header files up into their smallest
+ *  usable components..
+ * 
+ *  \file pkg_node.h
+ */
+
 class undo_group;
 namespace cwidget
 {
diff --git a/src/pkg_sortpolicy.h b/src/pkg_sortpolicy.h
index f4a98bba..17339013 100644
--- a/src/pkg_sortpolicy.h
+++ b/src/pkg_sortpolicy.h
@@ -17,11 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//
-// Package sorting policies.  Currently they just handle PkgIterator/VerIterator
-// pairs and a wrapper class integrates them with cwidget::widgets::tree.  If this can handle
-// everything useful, I'd like to keep it as is, since it's simpler than the
-// alternatives.
 
 #ifndef PKG_SORTPOLICY_H
 #define PKG_SORTPOLICY_H
@@ -29,6 +24,16 @@
 #include <apt-pkg/pkgcache.h>
 #include <cwidget/widgets/treeitem.h>
 
+/** \brief Package sorting policies
+ *
+ * 
+ *  Currently they just handle PkgIterator/VerIterator pairs and 
+ *  a wrapper class integrates them with cwidget::widgets::tree.  If this can handle
+ *  everything useful, I'd like to keep it as is, since it's simpler than the
+ * 
+ *  \file pkg_sortpolicy.h
+ */
+
 class pkg_tree_node;
 
 class pkg_sortpolicy
diff --git a/src/pkg_subtree.h b/src/pkg_subtree.h
index c9abfbcb..b70bca60 100644
--- a/src/pkg_subtree.h
+++ b/src/pkg_subtree.h
@@ -17,7 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  A subtree which contains packages (and other subtrees)
 
 #ifndef PKG_SUBTREE_H
 #define PKG_SUBTREE_H
@@ -26,6 +25,11 @@
 
 #include "pkg_node.h"
 
+/** \brief A subtree which contains packages (and other subtrees)
+ * 
+ *  \file pkg_subtree.h
+ */
+
 class pkg_subtree:public cwidget::widgets::subtree<pkg_tree_node>,
 		  public pkg_tree_node
 {
diff --git a/src/pkg_tree.h b/src/pkg_tree.h
index 5e6a5e66..d2f105d9 100644
--- a/src/pkg_tree.h
+++ b/src/pkg_tree.h
@@ -17,9 +17,7 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  Uses the cwidget::widgets::tree classes to display a tree containing packages.  A generic
-// version of this, suitable only for displaying the current state of the
-// package cache, is provided; it can be extended as needed.
+
 
 #ifndef PKG_TREE_H
 #define PKG_TREE_H
@@ -28,6 +26,16 @@
 
 #include <apt-pkg/pkgcache.h>
 
+/** \brief Uses the cwidget::widgets::tree classes to display a tree containing packages
+ *
+ * 
+ *  Uses the cwidget::widgets::tree classes to display a tree containing packages.  A generic
+ *  version of this, suitable only for displaying the current state of the
+ *  package cache, is provided; it can be extended as needed.
+ * 
+ *  \file pkg_tree.h
+ */
+
 class OpProgress;
 
 class pkg_grouppolicy;
diff --git a/src/pkg_ver_item.h b/src/pkg_ver_item.h
index 01bebd9f..1d2d64e1 100644
--- a/src/pkg_ver_item.h
+++ b/src/pkg_ver_item.h
@@ -17,7 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  Let you create tree nodes which refer to a particular version of a package.
 
 #ifndef PKG_VER_ITEM_H
 #define PKG_VER_ITEM_H
@@ -37,6 +36,10 @@
 #include <apt-pkg/depcache.h>
 #include <apt-pkg/pkgsystem.h>
 
+/** \brief Let you create tree nodes which refer to a particular version of a package.
+ * 
+ *  \file pkg_ver_item.h
+ */
 
 class pkg_ver_columnizer:public pkg_item::pkg_columnizer
 {
diff --git a/src/pkg_view.h b/src/pkg_view.h
index e927e90f..1352fb71 100644
--- a/src/pkg_view.h
+++ b/src/pkg_view.h
@@ -17,12 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-//  Stuff to manage "package views" and a way to create them.  Package views
-// are a collection of information displays about a package laid out (by a
-// table in our case).  A package view definition has a spot in itself for a
-// "main" widget, which allows configurations to be shared between several
-// different screens (unfortunately, it prevents me from, eg, having two
-// separate package trees at once :-( )
 
 #ifndef PKG_VIEW_H
 #define PKG_VIEW_H
@@ -35,6 +29,19 @@
 #include <list>
 #include <string>
 
+/** \brief Stuff to manage "package views" and a way to create them
+ *
+ * 
+ *  Stuff to manage "package views" and a way to create them.  Package views
+ *  are a collection of information displays about a package laid out (by a
+ *  table in our case).  A package view definition has a spot in itself for a
+ *  "main" widget, which allows configurations to be shared between several
+ *  different screens (unfortunately, it prevents me from, eg, having two
+ *  separate package trees at once :-( )
+ * 
+ *  \file pkg_view.h
+ */
+
 class menu_redirect;
 class package_view_item;
 class pkg_grouppolicy_factory;
diff --git a/src/progress.h b/src/progress.h
index 317a91ec..b3ce7ec5 100644
--- a/src/progress.h
+++ b/src/progress.h
@@ -17,7 +17,6 @@
 //  the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //  Boston, MA 02111-1307, USA.
 //
-//  A cwidget::widgets::widget that also acts as a progress bar.
 
 #ifndef VS_PROGRESS_H
 #define VS_PROGRESS_H
@@ -27,6 +26,11 @@
 
 #include <apt-pkg/progress.h>
 
+/** \brief A cwidget::widgets::widget that also acts as a progress bar.
+ * 
+ *  \file progress.h
+ */
+
 class progress : public cwidget::widgets::widget, public OpProgress
 {
 protected:
diff --git a/src/reason_fragment.h b/src/reason_fragment.h
index 365e20a6..975485f4 100644
--- a/src/reason_fragment.h
+++ b/src/reason_fragment.h
@@ -2,7 +2,6 @@
 //
 //  Copyright 2004 Daniel Burrows
 //
-// Code to convert a list of reasons to text fragments.
 
 #ifndef REASON_FRAGMENT_H
 #define REASON_FRAGMENT_H
@@ -11,6 +10,11 @@
 
 #include <generic/apt/infer_reason.h>
 
+/** \brief Code to convert a list of reasons to text fragments.
+ * 
+ *  \file reason_fragment.h
+ */
+
 namespace cwidget
 {
   class fragment;
diff --git a/src/solution_dialog.h b/src/solution_dialog.h
index 79288542..606ba2e1 100644
--- a/src/solution_dialog.h
+++ b/src/solution_dialog.h
@@ -17,11 +17,15 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Display the current solution.
 
 #ifndef SOLUTION_DIALOG_H
 #define SOLUTION_DIALOG_H
 
+/** \brief Display the current solution
+ * 
+ *  \file solution_dialog.h
+ */
+
 namespace cwidget
 {
   namespace util
diff --git a/src/solution_fragment.h b/src/solution_fragment.h
index 2b5df183..e06adf4d 100644
--- a/src/solution_fragment.h
+++ b/src/solution_fragment.h
@@ -17,8 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Code to convert an aptitude resolver solution and some of its
-// individual components to fragments.
 
 #ifndef SOLUTION_FRAGMENT_H
 #define SOLUTION_FRAGMENT_H
@@ -31,6 +29,12 @@
 // So passing aptitude_solution::action to a function is legal
 #include <generic/apt/aptitude_resolver_universe.h>
 
+/** \brief Code to convert an aptitude resolver solution and some of its
+ *  individual components to fragments.
+ * 
+ *  \file solution_fragment.h
+ */
+
 namespace cwidget
 {
   class fragment;
diff --git a/src/solution_item.h b/src/solution_item.h
index 3129ee87..77d9c95c 100644
--- a/src/solution_item.h
+++ b/src/solution_item.h
@@ -17,7 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Tree items that represent the contents of a solution.
 
 #ifndef SOLUTION_ITEM_H
 #define SOLUTION_ITEM_H
@@ -32,6 +31,11 @@
 
 #include <cwidget/widgets/treeitem.h>
 
+/** \brief Tree items that represent the contents of a solution
+ * 
+ *  \file solution_item.h
+ */
+
 namespace cwidget
 {
   class fragment;
diff --git a/src/solution_screen.h b/src/solution_screen.h
index 5bd23641..e6568d34 100644
--- a/src/solution_screen.h
+++ b/src/solution_screen.h
@@ -22,6 +22,9 @@
 
 #include <cwidget/generic/util/ref_ptr.h>
 
+/** \file solution_screen.h
+ */
+
 class aptitude_universe;
 template<class PackageUniverse> class generic_solution;
 namespace cwidget
diff --git a/src/trust.h b/src/trust.h
index 7c8f7178..06438308 100644
--- a/src/trust.h
+++ b/src/trust.h
@@ -2,13 +2,17 @@
 //
 //  Copyright 2004 Daniel Burrows
 //
-//  Various routines dealing with messages about package trust.
 
 #ifndef TRUST_H
 #define TRUST_H
 
 #include <apt-pkg/pkgcache.h>
 
+/** \brief Various routines dealing with messages about package trust.
+ * 
+ *  \file trust.h
+ */
+
 namespace cwidget
 {
   class fragment;
diff --git a/src/ui.h b/src/ui.h
index 5dc416a9..afe2a0a4 100644
--- a/src/ui.h
+++ b/src/ui.h
@@ -2,9 +2,6 @@
 //
 //  Copyright 2000,2001 Daniel Burrows
 //
-//  Global UI definitions and routines.  A lot of things here just provide a
-// single point for common actions so those actions can be customized later.
-// (eg, the progress-bar can appear in various forms)
 
 #ifndef UI_H
 #define UI_H
@@ -20,6 +17,16 @@
 
 #include <cwidget/widgets/editline.h> // Included for history support.
 
+/** \brief Global UI definitions and routines
+ *
+ * 
+ *  Global UI definitions and routines.  A lot of things here just provide a
+ *  single point for common actions so those actions can be customized later.
+ *  (eg, the progress-bar can appear in various forms)
+ * 
+ *  \file ui.h
+ */
+
 class OpProgress;
 
 class download_signal_log;
diff --git a/src/ui_download_manager.h b/src/ui_download_manager.h
index 0718bffe..9bcadf3b 100644
--- a/src/ui_download_manager.h
+++ b/src/ui_download_manager.h
@@ -17,8 +17,6 @@
 //   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 //   Boston, MA 02111-1307, USA.
 //
-// Glue code to go between the UI and the download manager/thread
-// stuff.
 
 #ifndef UI_DOWNLOAD_MANAGER_H
 #define UI_DOWNLOAD_MANAGER_H
@@ -32,6 +30,11 @@
 #include <sigc++/signal.h>
 #include <sigc++/trackable.h>
 
+/** \brief  Glue code to go between the UI and the download manager/thread stuff
+ * 
+ *  \file ui_download_manager.h
+ */
+
 class download_manager;
 class download_signal_log;
 class download_thread;
diff --git a/src/view_changelog.h b/src/view_changelog.h
index 77309a88..d2a1d8d8 100644
--- a/src/view_changelog.h
+++ b/src/view_changelog.h
@@ -2,14 +2,18 @@
 //
 //   Copyright 2004 Daniel Burrows
 //
-// A utility function to view a package's changelog.  Inserts widgets
-// into the main UI as appropriate.
 
 #ifndef VIEW_CHANGELOG_H
 #define VIEW_CHANGELOG_H
 
 #include <apt-pkg/pkgcache.h>
 
+/** \brief  A utility function to view a package's changelog.  Inserts widgets
+ *  into the main UI as appropriate.
+ * 
+ *  \file view_changelog.h
+ */
+
 void view_changelog(pkgCache::VerIterator ver);
 
 #endif