Review the header's doc comments and publish an API reference

[xcomart]

Folded into the v0.6.4 release (no version bump — the tag moves once this merges).

Doc comment review

src/libcmutils.h was nearly complete but had three kinds of problem.

21 gaps. The whole CMUTIL_HttpClient interface was undocumented — the typedef, all seven methods and the constructor — which is the type the REST client was just built on. Also Socket::SetSilent, ServerSocket::SetSilent and the matching silent argument of both listener constructors; a missing @param on Thread::GetId, Thread::GetName and XmlNode::GetName; a missing @return on CMUTIL_GetMem and CMUTIL_RWLockCreate; the key typedefs and the four platform shims.

58 markup errors. @typedef Name Description appeared 57 times, but Doxygen's @typedef takes a declaration, not a name and a description. Each one created a phantom symbol and left the real type undocumented — which is why nine enums (CMMemOper, CMLogLevel, CMSocketResult, …) had no documentation at all. They are plain @brief now, since a comment sitting on the entity already names it. Three @struct commands had the same problem, plus one unclosed <code> tag.

No structure. 6,300 lines rendered as one flat list. Now eighteen subjects, keeping the header's declaration order so a type is followed by its methods and then its constructor. Added @file, a @mainpage covering the CMCall convention and the CMUTIL_Init/CMUTIL_Clear lifecycle, and a group for the CMCall macros — which the main page points at and which belonged to no group.

doc/

File	Purpose
doc/Doxyfile	Only the settings that matter, not the 2,987-line default
doc/CMakeLists.txt	A docs target that appears only when doxygen is installed, never part of all
doc/README.md	What the topics contain, how to build, and the @typedef pitfall above

EXTRACT_ALL stays off with every documentation warning on, so a gap is reported in doc/doxygen.log rather than published as a blank page. The log is empty.

Publishing

Pages is currently build_type: legacy, serving the Jekyll-rendered README from master:/. The new Docs workflow keeps that landing page at / and adds the reference at /api/, building both on every push that touches them. Nothing generated is committed, and the job fails if doxygen writes anything to the log.

_config.yml now excludes the source tree — Jekyll had been mirroring src/, test/ and samples/ onto the site.

Requires a settings change to take effect: Pages → Build and deployment → Source must become GitHub Actions. Until then this workflow builds but does not deploy, and the existing legacy Jekyll deploy keeps running.

Verification

• doxygen 1.14.0: 0 warnings, 18 topic pages, 20 group pages, version renders as 0.6.4 on the title
• CMake docs target verified end to end; configures quietly when doxygen is absent
• Clean rebuild after the header changes: 0 compiler warnings, 15/15 ctest, 21/21 samples exit 0

🤖 Generated with Claude Code