00001 // -*- C++ -*- 00002 // $Id: mainpage,v 1.2 2006/12/22 01:44:59 marka Exp $ 00003 // 00004 // Doxygen text. Lines beginning with two slashes are comments; lines 00005 // beginning with three slashes are Doxygen input. 00006 00007 /// \mainpage 00008 /// \section mainpage_overview Overview 00009 /// \par 00010 /// 00011 /// This is the beginning of an internals manual for BIND9. It's 00012 /// still very rough in many places. 00013 /// 00014 /// \li See the files in doc/doxygen for the source to this page and 00015 /// the Doxygen configuration that generates the rest of the manual. 00016 /// 00017 /// \li See the tabs at the top of the screen to navigate through the 00018 /// generated documentation. 00019 /// 00020 /// \li See <a href="http://www.doxygen.org/">the Doxygen web site</a> 00021 /// for more information about Doxygen, including its manual. 00022 /// 00023 /// \section mainpage_knownissues Known Issues 00024 /// \par 00025 /// 00026 /// Known issues with our current use of Doxygen: 00027 /// 00028 /// \li In a major departure from previous attempts to use Doxygen 00029 /// with BIND9, this manual attempts to take the simplest approach 00030 /// to every choice Doxygen gives us. We don't generate fancy 00031 /// extra Doxygen tags files from the RFC database. We don't 00032 /// attempt to use Doxygen as a wrapper framework for other 00033 /// documentation (eg, ISC Tech Notes, the ARM, ...). We don't 00034 /// try to generate the list of files to document on the fly. 00035 /// Instead, we attempt to use Doxygen's native facilities 00036 /// wherever possible, on the assumption that we'll add new 00037 /// features later as we need them but should start as simply as 00038 /// we can. 00039 /// 00040 /// \li Our use of \\file is wrong in many places. We probably should 00041 /// be marking header files with the names by which we include 00042 /// them (eg, "dns/resolver.h"). Doxygen reports filename 00043 /// conflicts in a few cases where it can't work out which of 00044 /// several files to use. 00045 /// 00046 /// \li At the moment we're instructing Doxygen to document all 00047 /// functions, whether they have proper comment markup or not. 00048 /// This is a good way to see what's been marked up, but might not 00049 /// be the right approach in the long run. 00050 /// 00051 /// \li See doc/doxygen/doxygen-input-filter.in for local abbreviations. 00052 /// 00053 /// \li We're probably over-using the \\brief markup tag. 00054 /// 00055 /// \li We may in fact be confusing Doxygen to the point where it's 00056 /// not finding markup comments that it should. Needs 00057 /// investigation. 00058 /// 00059 /// \li At the moment I have all the cool "dot" stuff turned off, 00060 /// both because it's a distraction and because it slows down 00061 /// doxygen runs. Maybe after I get a faster desk machine. :) 00062 /// 00063 /// \li At the moment we're producing a single "BIND9 Internals" 00064 /// manual. One of our previous complications was an attempt to 00065 /// produce separate manuals for each library, then cross-link 00066 /// them. We might still need separate library manuals, but, if 00067 /// so, it might be easier to have the BIND9 Internals manual be a 00068 /// superset of the library manuals (ie, reuse the same source to 00069 /// produce differently scoped manuals). Would certainly be 00070 /// simpler than the cross-linking mess, but partly it's a 00071 /// question of how we want to present the material. 00072 /// 00073 /// \li Doxygen is slanted towards C++. It can be tuned towards plain 00074 /// old C, but the C++ bias still shows up in places, eg, the lack 00075 /// of top-level menu support for functions (in C++, the basic 00076 /// unit of programming is the class, which Doxygen does support 00077 /// directly). This is a bit annoying, but not all that 00078 /// critical. 00079 /// 00080 /// \li If we ever get really ambitious, we might try processing 00081 /// Doxygen's XML output, which is basicly a dump of what Doxygen 00082 /// was able to scrape from the sources. This would be a major 00083 /// project, just something to think about if there's something we 00084 /// really don't like about the output Doxygen generates. Punt 00085 /// for now.