| blob | 0e6bc2e787b781b31a32f8f99e0a401780b3aa21 |
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.
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.