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)

5 files changed, 62 insertions, 7 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")
diff --git a/cmake/BuildDeps.cmake b/cmake/BuildDeps.cmake
index d535e0a..1f64e1f 100644
--- a/cmake/BuildDeps.cmake
+++ b/cmake/BuildDeps.cmake
@@ -1,9 +1,17 @@
+# ======================================
+#  BuildDeps.cmake
+# ======================================
+#
+# Configures, builds, and installs the open62541 library into a
+# local prefix under the build tree.  Skips the build when the
+# installed shared library already exists.  After installation,
+# open62541 is imported via find_package so downstream targets
+# can link against open62541::open62541.
+
 set(OPEN62541_SOURCE_DIR "${CMAKE_SOURCE_DIR}/deps/open62541")
 set(OPEN62541_BUILD_DIR "${CMAKE_BINARY_DIR}/deps/open62541")
 set(OPEN62541_INSTALL_DIR "${CMAKE_BINARY_DIR}/deps/open62541-install")
 
-# --- open62541 ---
-
 if(NOT EXISTS "${OPEN62541_SOURCE_DIR}/CMakeLists.txt")
   message(
     FATAL_ERROR
diff --git a/src/config.h b/src/config.h
index ee29ada..649278d 100644
--- a/src/config.h
+++ b/src/config.h
@@ -1,3 +1,6 @@
+#ifndef DISCOVERY_CONFIG_H
+#define DISCOVERY_CONFIG_H
+
 /**
  * @file  config.h
  * @brief Simple key=value configuration file parser.
@@ -8,9 +11,6 @@
  * trustList).
  */
 
-#ifndef DISCOVERY_CONFIG_H
-#define DISCOVERY_CONFIG_H
-
 #include <stddef.h>
 
 /**
diff --git a/src/server_register.c b/src/server_register.c
index 5bdba8e..d259961 100644
--- a/src/server_register.c
+++ b/src/server_register.c
@@ -154,6 +154,7 @@ main (int argc, char **argv)
 
   if (strcmp (clientAuthMode, "anonymous") == 0)
     {
+      /* No credentials needed. */
     }
   else if (strcmp (clientAuthMode, "user") == 0)
     {
diff --git a/tools/generate_certificate.sh b/tools/generate_certificate.sh
index 3b2c54a..81fe947 100755
--- a/tools/generate_certificate.sh
+++ b/tools/generate_certificate.sh
@@ -2,8 +2,18 @@
 # generate_certificate.sh — Create a self-signed X.509 certificate for
 # open62541 OPC UA applications.  Outputs DER-encoded certificate and
 # private-key files suitable for the demo programs in this project.
+#
+# Arguments:
+#   $1  certs_dir  — output directory for generated files (created if missing)
+#   $2  name       — identity name (e.g. "ServerLDS", "ClientFindServers")
+#   $3  uri        — (optional) application URI; defaults to urn:bobink.<name>
+#
+# Produces:
+#   <certs_dir>/<name>_cert.der   — DER-encoded X.509 certificate
+#   <certs_dir>/<name>_cert.pem   — PEM-encoded X.509 certificate
+#   <certs_dir>/<name>_key.der    — DER-encoded RSA private key
 
-set -euo pipefail
+set -euo pipefail # Fail fast; no unset vars; catch pipe failures.
 
 if [ $# -lt 2 ] || [ $# -gt 3 ]; then
   echo "Usage: generate_certificate.sh <certs_dir> <name> [uri]" >&2