summaryrefslogtreecommitdiffstats
path: root/doc/doxygen/mainpage
blob: 618ebb8e9b390efdf25ad5e9ed07009cb3fca463 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
// -*- C++ -*-
//
// Doxygen text.  Lines beginning with two slashes are comments; lines
// beginning with three slashes are Doxygen input.
//
// Copyright (C) Internet Systems Consortium, Inc. ("ISC")
//
// SPDX-License-Identifier: MPL-2.0
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0.  If a copy of the MPL was not distributed with this
// file, you can obtain one at https://mozilla.org/MPL/2.0/.
//
// See the COPYRIGHT file distributed with this work for additional
// information regarding copyright ownership.


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