From 8e407cc514d316e7248e2f1b155a1a6ed54c1219 Mon Sep 17 00:00:00 2001
From: Jon Shallow <supjps-libcoap@jpshallow.com>
Date: Thu, 3 Oct 2024 15:43:57 +0100
Subject: [PATCH] documentation: Various doc tidyup

configure.ac: Tidy up coap_defines.h generation

doc/upgrade_4.3.4_4.3.5.txt: Document upgrade requirements

doc/Makefile.am: Include upgrade_4.3.4_4.3.5.txt

cmake_coap_defines.h.in: Add brief description
src/coap_sha1.c: Add in brief description

Note: With Ubuntu 24.04.01, when running a2x, spurious entries
 <unknown>:1: SyntaxWarning: invalid escape sequence '\S'
occur. Fixed by https://github.com/asciidoc-py/asciidoc-py/pull/267
---
 cmake_coap_defines.h.in     | 5 +++++
 configure.ac                | 4 +++-
 doc/Makefile.am             | 3 ++-
 doc/upgrade_4.3.4_4.3.5.txt | 5 +++++
 src/coap_sha1.c             | 5 +++++
 5 files changed, 20 insertions(+), 2 deletions(-)
 create mode 100644 doc/upgrade_4.3.4_4.3.5.txt

diff --git a/cmake_coap_defines.h.in b/cmake_coap_defines.h.in
index 5474fb15f3..7069a88a0c 100644
--- a/cmake_coap_defines.h.in
+++ b/cmake_coap_defines.h.in
@@ -9,6 +9,11 @@
  * of use.
  */
 
+/**
+ * @file coap_defines.h
+ * @brief List of libcoap library build defines
+ */
+
 #ifndef COAP_DEFINES_H_
 #define COAP_DEFINES_H_
 
diff --git a/configure.ac b/configure.ac
index e913780796..97733b5c1d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1554,7 +1554,9 @@ else
 fi
 
 mkdir -p include/coap$LIBCOAP_API_VERSION
-LT_TEMP=`grep -B2 " COAP_" coap_config.h > include/coap$LIBCOAP_API_VERSION/coap_defines.h`
+head -19 cmake_coap_defines.h.in > include/coap$LIBCOAP_API_VERSION/coap_defines.h
+LT_TEMP=`grep -B2 " COAP_" coap_config.h >> include/coap$LIBCOAP_API_VERSION/coap_defines.h`
+tail -2 cmake_coap_defines.h.in >> include/coap$LIBCOAP_API_VERSION/coap_defines.h
 if test "x$LT_TEMP" != "x" ; then
     AC_MSG_ERROR([Unable to build coap_defines.h])
 fi
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ad58bf0da2..ae57e65f4c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -21,6 +21,7 @@ EXTRA_DIST = \
   upgrade_4.3.1_4.3.2.txt \
   upgrade_4.3.2_4.3.3.txt \
   upgrade_4.3.3_4.3.4.txt \
+  upgrade_4.3.4_4.3.5.txt \
   main.md \
   module_api_wrap.h
 
@@ -244,7 +245,7 @@ man-page-build: upg-page-build man-page-start
 	done
 
 if BUILD_MANPAGES
-UPG_LIST = upgrade_4.2.1_4.3.0.txt upgrade_4.3.0_4.3.1.txt upgrade_4.3.1_4.3.2.txt upgrade_4.3.2_4.3.3.txt upgrade_4.3.3_4.3.4.txt
+UPG_LIST = upgrade_4.2.1_4.3.0.txt upgrade_4.3.0_4.3.1.txt upgrade_4.3.1_4.3.2.txt upgrade_4.3.2_4.3.3.txt upgrade_4.3.3_4.3.4.txt upgrade_4.3.4_4.3.5.txt
 
 upg-page-build:
 	@for FILE in $(UPG_LIST) ; do \
diff --git a/doc/upgrade_4.3.4_4.3.5.txt b/doc/upgrade_4.3.4_4.3.5.txt
new file mode 100644
index 0000000000..04b888986e
--- /dev/null
+++ b/doc/upgrade_4.3.4_4.3.5.txt
@@ -0,0 +1,5 @@
+= Upgrade from 4.3.4 to 4.3.5
+
+== Summary
+
+No code or binary changes required.
diff --git a/src/coap_sha1.c b/src/coap_sha1.c
index c2b16ca5ed..0535cc698d 100644
--- a/src/coap_sha1.c
+++ b/src/coap_sha1.c
@@ -63,6 +63,11 @@
  * Reformatted as appropriate.
  */
 
+/**
+ * @file coap_sha1.c
+ * @brief SHA-1 handling functions
+ */
+
 #include "coap3/coap_libcoap_build.h"
 
 #if COAP_WS_SUPPORT && !defined(COAP_WITH_LIBOPENSSL) && !defined(COAP_WITH_LIBGNUTLS) && !defined(COAP_WITH_LIBMBEDTLS) && !defined(COAP_WITH_LIBWOLFSSL)