[#1945] address review

- generate kea-messages.rst automatically on make -C doc/sphinx
- add disclaimer header that debug-messages.rst and kea-messages.rst are
  generated
- minor changes to debug level variable names
- do not write section "Messages printed" in tools/check-messages.py if
  there are no messages

Author: andrei-pavel

doc/sphinx/Makefile.am

@@ -61,9 +61,9 @@ api_files =
 include $(top_srcdir)/src/share/api/api_files.mk
 
 if HAVE_PDFLATEX
-all: html mans pdf text
+all: kea-messages.rst html mans pdf text
 else
-all: html mans text
+all: kea-messages.rst html mans text
 endif
 
 # build the list of message files
@@ -73,8 +73,7 @@ mes_files.mk: mes-files.txt
 mes-files.txt:
 	@find ../.. -type f -name '*.mes' | sort -V | sed 's#^../../##g' > $@
 
-# this rule is only used for development purposes and is not used in official
-# build process as kea-messages.rst is always generated via sphinx's conf.py
+# Used in official build process. kea-messages.rst is generated via mes2doc.py.
 $(srcdir)/kea-messages.rst: mes2doc.py
 	$(PYTHON) $(srcdir)/mes2doc.py -o $@
 

doc/sphinx/debug-messages.rst

@@ -1,3 +1,6 @@
+..
+    File generated by "./tools/check-messages.py -a". Do not edit by hand.
+
 Messages printed on debuglevel 0
 ================================
 

doc/sphinx/kea-messages.rst

@@ -1,3 +1,6 @@
+..
+    File generated by "doc/sphinx/mes2doc.py" or by "make -C doc/sphinx". Do not edit by hand.
+
 .. _kea-messages:
 
 ###################

doc/sphinx/mes2doc.py

@@ -78,7 +78,10 @@ def read_input_files(files):
 
 
 def generate_rst(messages):
-    rst = '''.. _kea-messages:
+    rst = '..\n'
+    rst += '    File generated by "doc/sphinx/mes2doc.py" or by "make -C doc/sphinx". Do not edit by hand.\n\n'
+
+    rst += '''.. _kea-messages:
 
 ###################
 Kea Messages Manual

src/bin/dhcp4/dhcp4_messages.mes

@@ -980,13 +980,13 @@ that the hint hasn't been sent.
 
 % DHCP4_REQUIRED_CLASS_EVAL_ERROR %1: Expression '%2' evaluated to %3
 This error message indicates that there a problem was encountered while
-evaluating an expression of a client class that was marked as required.
+evaluating an expression of a required client class that was marked as required.
 A description of the problem is printed.
 
 % DHCP4_REQUIRED_CLASS_EVAL_RESULT %1: Expression '%2' evaluated to %3
 Logged at debug log level 50.
-This debug message indicates that the expression of a client class has been
-successfully evaluated. The client class name and the result value of the
+This debug message indicates that the expression of a required client class has
+been successfully evaluated. The client class name and the result value of the
 evaluation are printed.
 
 % DHCP4_RESERVATIONS_LOOKUP_FIRST_ENABLED Multi-threading is enabled and host reservations lookup is always performed first.

src/bin/dhcp6/dhcp6_messages.mes

@@ -985,13 +985,13 @@ expected IAID and IAID found respectively.
 
 % DHCP6_REQUIRED_CLASS_EVAL_ERROR %1: Expression '%2' evaluated to %3
 This error message indicates that there a problem was encountered while
-evaluating an expression of a client class that was marked as required.
+evaluating an expression of a required client class that was marked as required.
 A description of the problem is printed.
 
 % DHCP6_REQUIRED_CLASS_EVAL_RESULT %1: Expression '%2' evaluated to %3
 Logged at debug log level 50.
-This debug message indicates that the expression of a client class has been
-successfully evaluated. The client class name and the result value of the
+This debug message indicates that the expression of a required client class has
+been successfully evaluated. The client class name and the result value of the
 evaluation are printed.
 
 % DHCP6_REQUIRED_OPTIONS_CHECK_FAIL %1: %2 message received from %3 failed the following check: %4

src/lib/asiodns/io_fetch.cc

@@ -46,7 +46,7 @@ namespace asiodns {
 
 const int DBG_IMPORTANT = DBGLVL_TRACE_BASIC;
 const int DBG_COMMON = DBGLVL_TRACE_DETAIL;
-const int DBG_ALL = DBGLVL_TRACE_ALL;
+const int DBG_VERBOSE = DBGLVL_TRACE_TECHNICAL;
 
 /// @brief IOFetch Data
 ///
@@ -316,7 +316,7 @@ IOFetch::stop(Result result) {
                 break;
 
             case SUCCESS:
-                LOG_DEBUG(logger, DBG_ALL, ASIODNS_FETCH_COMPLETED).
+                LOG_DEBUG(logger, DBG_VERBOSE, ASIODNS_FETCH_COMPLETED).
                     arg(data_->remote_rcv->getAddress().toText()).
                     arg(data_->remote_rcv->getPort());
                 break;

src/lib/log/log_dbglevels.cc

@@ -20,7 +20,8 @@ extern const int DBGLVL_TRACE_BASIC = 40;
 extern const int DBGLVL_TRACE_BASIC_DATA = 45;
 extern const int DBGLVL_TRACE_DETAIL = 50;
 extern const int DBGLVL_TRACE_DETAIL_DATA = 55;
-extern const int DBGLVL_TRACE_ALL = 70;
+extern const int DBGLVL_TRACE_TECHNICAL = 70;
+extern const int DBGLVL_TRACE_TECHNICAL_DATA = 90;
 
 }  // namespace log
 }  // namespace isc

src/lib/log/log_dbglevels.h

@@ -77,8 +77,11 @@ extern const int DBGLVL_TRACE_DETAIL;
 /// @brief Trace data associated with detailed operations.
 extern const int DBGLVL_TRACE_DETAIL_DATA;
 
-/// @brief The highest level of debug logging.
-extern const int DBGLVL_TRACE_ALL;
+/// @brief Trace technical operations.
+extern const int DBGLVL_TRACE_TECHNICAL;
+
+/// @brief Trace data associated with technical operations.
+extern const int DBGLVL_TRACE_TECHNICAL_DATA;
 
 }  // log namespace
 }  // isc namespace

tools/check-messages.py

@@ -149,16 +149,22 @@ def check_placeholder_ids(messages):
 def generate_page_with_messages_printed_on_each_debug_level(messages, debug_levels):
     content = []
     for log_level in sorted(set(debug_levels.values())):
+        messages_at_this_log_level = [(message_id, message) for message_id, message in sorted(messages.items())
+                                      if message['debug_log_level_line'] == f'Logged at debug log level {log_level}.']
+        if len(messages_at_this_log_level) == 0:
+            # Do not write "Messages printed" subtitle if there are no messages.
+            continue
         subtitle = f'Messages printed on debuglevel {log_level}'
         content.append(subtitle)
         content.append('=' * len(subtitle))
         content.append('\n')
-        for message_id, message in sorted(messages.items()):
-            if message['debug_log_level_line'] == f'Logged at debug log level {log_level}.':
-                content.append(f'- {message_id}')
+        for message_id, message in messages_at_this_log_level:
+            content.append(f'- {message_id}')
         content.append('\n')
     parent_dir = os.path.dirname(os.path.realpath(os.path.abspath(sys.argv[0])))
     with open(f'{parent_dir}/../doc/sphinx/debug-messages.rst', 'w', encoding='utf-8') as f:
+        f.write('..\n')
+        f.write('    File generated by "./tools/check-messages.py -a". Do not edit by hand.\n\n')
         for i in content:
             f.write(i)
             f.write('\n')