1// -*- C++ -*- 2// Id: mainpage,v 1.2 2006/12/22 01:44:59 marka Exp 3// 4// Doxygen text. Lines beginning with two slashes are comments; lines 5// beginning with three slashes are Doxygen input. 6 7/// \mainpage 8/// \section mainpage_overview Overview 9/// \par 10/// 11/// This is the beginning of an internals manual for BIND9. It's 12/// still very rough in many places. 13/// 14/// \li See the files in doc/doxygen for the source to this page and 15/// the Doxygen configuration that generates the rest of the manual. 16/// 17/// \li See the tabs at the top of the screen to navigate through the 18/// generated documentation. 19/// 20/// \li See <a href="http://www.doxygen.org/">the Doxygen web site</a> 21/// for more information about Doxygen, including its manual. 22/// 23/// \section mainpage_knownissues Known Issues 24/// \par 25/// 26/// Known issues with our current use of Doxygen: 27/// 28/// \li In a major departure from previous attempts to use Doxygen 29/// with BIND9, this manual attempts to take the simplest approach 30/// to every choice Doxygen gives us. We don't generate fancy 31/// extra Doxygen tags files from the RFC database. We don't 32/// attempt to use Doxygen as a wrapper framework for other 33/// documentation (eg, ISC Tech Notes, the ARM, ...). We don't 34/// try to generate the list of files to document on the fly. 35/// Instead, we attempt to use Doxygen's native facilities 36/// wherever possible, on the assumption that we'll add new 37/// features later as we need them but should start as simply as 38/// we can. 39/// 40/// \li Our use of \\file is wrong in many places. We probably should 41/// be marking header files with the names by which we include 42/// them (eg, "dns/resolver.h"). Doxygen reports filename 43/// conflicts in a few cases where it can't work out which of 44/// several files to use. 45/// 46/// \li At the moment we're instructing Doxygen to document all 47/// functions, whether they have proper comment markup or not. 48/// This is a good way to see what's been marked up, but might not 49/// be the right approach in the long run. 50/// 51/// \li See doc/doxygen/doxygen-input-filter.in for local abbreviations. 52/// 53/// \li We're probably over-using the \\brief markup tag. 54/// 55/// \li We may in fact be confusing Doxygen to the point where it's 56/// not finding markup comments that it should. Needs 57/// investigation. 58/// 59/// \li At the moment I have all the cool "dot" stuff turned off, 60/// both because it's a distraction and because it slows down 61/// doxygen runs. Maybe after I get a faster desk machine. :) 62/// 63/// \li At the moment we're producing a single "BIND9 Internals" 64/// manual. One of our previous complications was an attempt to 65/// produce separate manuals for each library, then cross-link 66/// them. We might still need separate library manuals, but, if 67/// so, it might be easier to have the BIND9 Internals manual be a 68/// superset of the library manuals (ie, reuse the same source to 69/// produce differently scoped manuals). Would certainly be 70/// simpler than the cross-linking mess, but partly it's a 71/// question of how we want to present the material. 72/// 73/// \li Doxygen is slanted towards C++. It can be tuned towards plain 74/// old C, but the C++ bias still shows up in places, eg, the lack 75/// of top-level menu support for functions (in C++, the basic 76/// unit of programming is the class, which Doxygen does support 77/// directly). This is a bit annoying, but not all that 78/// critical. 79/// 80/// \li If we ever get really ambitious, we might try processing 81/// Doxygen's XML output, which is basicly a dump of what Doxygen 82/// was able to scrape from the sources. This would be a major 83/// project, just something to think about if there's something we 84/// really don't like about the output Doxygen generates. Punt 85/// for now. 86