diff options
author | Daniel Burrows <dburrows@debian.org> | 2008-04-24 16:56:03 -0700 |
---|---|---|
committer | Daniel Burrows <dburrows@debian.org> | 2008-04-24 16:56:03 -0700 |
commit | 034a9b5881ba97dba894f4a5ebb5cdca253f9a6d (patch) | |
tree | 915267c46a28e2eb96b3bf78f3d2773122db05bf | |
parent | 6197092149bdb032fc9ccdb6ce95f596d9b833e3 (diff) | |
parent | 18c40203d8466a9cc391a5d59d85fca645a656fc (diff) | |
download | aptitude-034a9b5881ba97dba894f4a5ebb5cdca253f9a6d.tar.gz |
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; @@ -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 |