mainpage revision 29747dfe5e073a299b3681e01f5c55540f8bfed7
619bd403265ce0880989ba6f8324b010949851bcSumit Bose// -*- C++ -*-
619bd403265ce0880989ba6f8324b010949851bcSumit Bose// $Id: mainpage,v 1.2 2006/12/22 01:44:59 marka Exp $
619bd403265ce0880989ba6f8324b010949851bcSumit Bose// Doxygen text. Lines beginning with two slashes are comments; lines
619bd403265ce0880989ba6f8324b010949851bcSumit Bose// beginning with three slashes are Doxygen input.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \mainpage
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \section mainpage_overview Overview
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// This is the beginning of an internals manual for BIND9. It's
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// still very rough in many places.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li See the files in doc/doxygen for the source to this page and
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// the Doxygen configuration that generates the rest of the manual.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li See the tabs at the top of the screen to navigate through the
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// generated documentation.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li See <a href="http://www.doxygen.org/">the Doxygen web site</a>
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// for more information about Doxygen, including its manual.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \section mainpage_knownissues Known Issues
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// Known issues with our current use of Doxygen:
fd94a375467ade9233e34513863571fc51fec2edStephen Gallagher/// \li In a major departure from previous attempts to use Doxygen
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// with BIND9, this manual attempts to take the simplest approach
7d9f54f5ec7c72336c4f69dbf20d55f1f64b88d2Jan Zeleny/// to every choice Doxygen gives us. We don't generate fancy
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// extra Doxygen tags files from the RFC database. We don't
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// attempt to use Doxygen as a wrapper framework for other
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// documentation (eg, ISC Tech Notes, the ARM, ...). We don't
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// try to generate the list of files to document on the fly.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// Instead, we attempt to use Doxygen's native facilities
114c1ed8ec72b43f04527b4f3b4f0940c1fb2c54Pavel Březina/// wherever possible, on the assumption that we'll add new
114c1ed8ec72b43f04527b4f3b4f0940c1fb2c54Pavel Březina/// features later as we need them but should start as simply as
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li Our use of \\file is wrong in many places. We probably should
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// be marking header files with the names by which we include
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// them (eg, "dns/resolver.h"). Doxygen reports filename
940e033c0c427d02a34347dbd2f4443fa625b111Jakub Hrozek/// conflicts in a few cases where it can't work out which of
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// several files to use.
684d1b48b5582a1bf7812b8c3c663592dc6dfed9Pavel Březina/// \li At the moment we're instructing Doxygen to document all
684d1b48b5582a1bf7812b8c3c663592dc6dfed9Pavel Březina/// functions, whether they have proper comment markup or not.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// This is a good way to see what's been marked up, but might not
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// be the right approach in the long run.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li See doc/doxygen/doxygen-input-filter.in for local abbreviations.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li We're probably over-using the \\brief markup tag.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li We may in fact be confusing Doxygen to the point where it's
a8e7d395b4aab4e7a236aebf162a844ae51cc7dbLukas Slebodnik/// not finding markup comments that it should. Needs
a8e7d395b4aab4e7a236aebf162a844ae51cc7dbLukas Slebodnik/// investigation.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li At the moment I have all the cool "dot" stuff turned off,
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// both because it's a distraction and because it slows down
a8e7d395b4aab4e7a236aebf162a844ae51cc7dbLukas Slebodnik/// doxygen runs. Maybe after I get a faster desk machine. :)
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li At the moment we're producing a single "BIND9 Internals"
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// manual. One of our previous complications was an attempt to
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// produce separate manuals for each library, then cross-link
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// them. We might still need separate library manuals, but, if
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// so, it might be easier to have the BIND9 Internals manual be a
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// superset of the library manuals (ie, reuse the same source to
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// produce differently scoped manuals). Would certainly be
70a33bdf7db34fe4d1ba194cf9ea28c758719b4bJakub Hrozek/// simpler than the cross-linking mess, but partly it's a
70a33bdf7db34fe4d1ba194cf9ea28c758719b4bJakub Hrozek/// question of how we want to present the material.
70a33bdf7db34fe4d1ba194cf9ea28c758719b4bJakub Hrozek/// \li Doxygen is slanted towards C++. It can be tuned towards plain
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// old C, but the C++ bias still shows up in places, eg, the lack
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// of top-level menu support for functions (in C++, the basic
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// unit of programming is the class, which Doxygen does support
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// directly). This is a bit annoying, but not all that
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// critical.
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// \li If we ever get really ambitious, we might try processing
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// Doxygen's XML output, which is basicly a dump of what Doxygen
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// was able to scrape from the sources. This would be a major
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// project, just something to think about if there's something we
619bd403265ce0880989ba6f8324b010949851bcSumit Bose/// really don't like about the output Doxygen generates. Punt