Add comments to build files and shell scripts, fix minor inconsistencies

- CMakeLists.txt: add file-level comment, section banners, target
  docs, and test-section explanation
- cmake/BuildDeps.cmake: add file-level comment describing the
  configure/build/install workflow
- tools/generate_certificate.sh: document arguments and outputs in
  header block, comment set -euo pipefail
- src/config.h: move include guard before Doxygen block (match
  common.h)
- src/server_register.c: add comment to empty anonymous-auth block
  (match client_find_servers.c)

1 files changed, 37 insertions, 1 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 93e472d..36c5167 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,3 +1,15 @@
+# ======================================
+#  OPC UA Discovery — Top-level build
+# ======================================
+#
+# Builds three programs that demonstrate OPC UA discovery:
+#   ServerLDS          — Local Discovery Server
+#   ServerRegister     — Server that registers with the LDS
+#   ClientFindServers  — Client that queries the LDS
+#
+# All programs link against DiscoveryCommon (shared helpers and
+# config parser) which in turn depends on open62541.
+
 cmake_minimum_required(VERSION 4.0)
 project(OpcUaDiscovery C)
 
@@ -6,18 +18,33 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 include(cmake/BuildDeps.cmake)
 
+# ======================================
+#  Libraries and executables
+# ======================================
+
+# Shared helpers (file loading, security factories, config parser)
+# used by all three programs.
 add_library(DiscoveryCommon STATIC src/common.c src/config.c)
 target_link_libraries(DiscoveryCommon open62541::open62541)
 
+# Queries the LDS for registered servers and their endpoints.
 add_executable(ClientFindServers src/client_find_servers.c)
 target_link_libraries(ClientFindServers DiscoveryCommon)
 
+# Runs the Local Discovery Server that other servers register with.
 add_executable(ServerLDS src/server_lds.c)
 target_link_libraries(ServerLDS DiscoveryCommon)
 
+# Runs a server that periodically registers itself with the LDS.
 add_executable(ServerRegister src/server_register.c)
 target_link_libraries(ServerRegister DiscoveryCommon)
 
+# ======================================
+#  Documentation
+# ======================================
+
+# Builds the open62541 HTML documentation via Sphinx.
+# Requires python3-sphinx, python3-sphinx-rtd-theme, graphviz.
 option(BUILD_DOC "Build open62541 HTML documentation" OFF)
 if(BUILD_DOC)
   add_custom_target(doc
@@ -26,7 +53,16 @@ if(BUILD_DOC)
     VERBATIM)
 endif()
 
-# ── Integration tests ───────────────────────────────────────────
+# ======================================
+#  Integration tests
+# ======================================
+#
+# Each test exercises a combination of security mode/policy and
+# authentication method.  _test_names and _test_policies are
+# parallel lists: the Nth name uses the Nth policy.  Each name
+# corresponds to a config directory under tests/ containing
+# server_lds.conf, server_register.conf, client_find_servers.conf.
+
 enable_testing ()
 
 set (_test_script "${CMAKE_SOURCE_DIR}/tests/run_test.sh")