[#1520] add debug symbols section to dev guide

CONTRIBUTING.md

@@ -9,7 +9,7 @@ Here's a quick list of how to contribute a patch:
 2. **open an issue** in [Kea project](https://gitlab.isc.org/isc-projects/kea/issues/new), make sure
    it describes what you want to fix and **why**
 3. **ask someone from the ISC team to give you permission to fork Kea** (ask @tomek, @vicky, @ondrej
-   or @godfryd or basically anyone from the Kea dev team)
+   or basically anyone from the Kea dev team)
 4. **fork Kea code**: go to Kea project page, click [Fork button](https://gitlab.isc.org/isc-projects/kea/forks/new).
    If you can't, you didn't complete step 3.
 5. **Implement your fix or feature, push code** to your repo. Make sure it compiles, has unit-tests,
@@ -188,8 +188,9 @@ make distcheck
 
 There are other useful switches which can be passed to configure. It is always a good idea to use
 `–enable-logger-checks`, which does sanity checks on logger parameters. Use `–-enable-debug` to
-enable various additional consistency checks that reduce performance but help during development. If
+enable debug symbols and various additional consistency checks that reduce performance but help
-you happen to modify anything in the documentation, use `–-enable-generate-docs`. If you are
+during development.
+If you happen to modify anything in the documentation, use `–-enable-generate-docs`. If you are
 modifying DHCP code, you are likely to be interested in enabling a non-default database backends for
 DHCP. Note that if the backend is not enabled, the database-specific unit-tests are skipped.  To
 enable the MySQL backend, use the switch `–with-mysql`; for PostgreSQL, use `–with-pgsql`.
@@ -216,7 +217,7 @@ particular, new users can't fork the code on their own and it requires someone f
 grant the ability to fork projects.  Fortunately, this is easy to do and we glady do this for anyone
 who asks and provides a good reason. "I'd like to fix bug X or develop feature Y" is an excellent
 reason. The best place for asking is either kea-dev or asking in a comment in your issue. Make sure
-you put a name tag (@tomek, @godfryd, @vicky or @ondrej). When you write a comment in an issue or
+you put a name tag (@tomek, @vicky or @ondrej). When you write a comment in an issue or
 merge request and add a name tag on it, the user is automatically notified.
 
 Once you fork the Kea code in gitlab, you have your own copy and you can commit your changes there

doc/devel/Makefile.am

@@ -5,6 +5,7 @@ EXTRA_DIST += config-backend.dox
 EXTRA_DIST += congestion-handling.dox
 EXTRA_DIST += contribute.dox
 EXTRA_DIST += cross-compile.dox
+EXTRA_DIST += debug.dox
 EXTRA_DIST += doc.dox
 EXTRA_DIST += fuzz.dox
 EXTRA_DIST += mainpage.dox

doc/devel/debug.dox

@@ -0,0 +1,26 @@
+// Copyright (C) 2023 Internet Systems Consortium, Inc. ("ISC")
+//
+// 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 http://mozilla.org/MPL/2.0/.
+
+/**
+
+ @page debug Debugging Kea
+
+@section debugSymbols Enabling debug symbols
+
+The --enable-debug flag can be useful when developing, since it
+makes the compiler produce more abundant debugging information that
+can be read by a debugger.
+
+Some compilers don't document some of the flags, such as clang for
+-g3. However, practice shows that clang behaves the same way as g++
+in that regard. As an experiment, providing -g4 results in
+`error: unknown argument: '-g4'`, but providing -g3 succesfully
+compiles, and supposedly puts it into effect.
+
+On top of that, the flag enables log4cplus's own logging, and adds
+more sanity checks in DNS code.
+
+*/

doc/devel/mainpage.dox

@@ -154,7 +154,8 @@
  * - @subpage LoggingApi
  * - @subpage SocketSessionUtility
  * - @subpage crossCompile
+ * - @subpage debug
  * - @subpage docs
- * - <a href="./doxygen-error.log">Documentation warnings and errors</a>
+ * - <a href="./doxygen-error.log"><b>Documentation Warnings and Errors</b></a>
  *
  */