Docs: add coding conventions doc and improve Doxygen infrastructure

CMakeLists.txt

@@ -55,6 +55,11 @@ if(CODES_SANITIZER)
     add_link_options(-fsanitize=${CODES_SANITIZER})
 endif()
 
+# Opt-in Doxygen API docs. OFF by default and never part of `all`; the docs
+# subdir registers an on-demand `docs` target (see doc/CMakeLists.txt). Output
+# lands in the build tree, not the source tree.
+option(CODES_BUILD_DOXYGEN "Build Doxygen API docs" OFF)
+
 #prevent cmake from stripping the runtime path (important if shared libraries are imported)
 SET(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
 
@@ -276,6 +281,10 @@ configure_file(codes_config.h.cmake.in codes_config.h)
 
 add_subdirectory(doc/example)
 
+if(CODES_BUILD_DOXYGEN)
+    add_subdirectory(doc)
+endif()
+
 # Tests are gated solely on BUILD_TESTING (the canonical CTest knob). A
 # $<CONFIG:...> genex can't gate this since add_subdirectory() runs at
 # configure time, and the old `STREQUAL "RELEASE"` compare never matched the

README.md

@@ -245,6 +245,10 @@ CODES provides comprehensive simulation capabilities for:
 
 ## Contributing
 
+For naming, file extensions, header guards, and how LP state must be constructed,
+see the [coding conventions](doc/dev/conventions.md). Formatting is machine-checked
+(below).
+
 ### Code formatting
 
 This repo uses [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to keep C/C++ style consistent. The rules live in [`.clang-format`](.clang-format) at the repo root; configure your editor to pick it up:

doc/CMakeLists.txt

@@ -0,0 +1,50 @@
+# CODES API documentation (Doxygen).
+#
+# Reached only when -DCODES_BUILD_DOXYGEN=ON (see the option in the top-level
+# CMakeLists). Registers an on-demand `docs` target — not built by `all`:
+#
+#     cmake -S . -B build -DCODES_BUILD_DOXYGEN=ON
+#     cmake --build build --target docs
+#
+# The doc-comment convention (which entities get /** */ comments, and that there
+# is no mass backfill) lives in doc/dev/conventions.md.
+
+find_package(Doxygen)
+if(NOT DOXYGEN_FOUND)
+    message(WARNING
+        "CODES_BUILD_DOXYGEN=ON but Doxygen was not found; the `docs` target "
+        "will not be registered. Install Doxygen or set CODES_BUILD_DOXYGEN=OFF.")
+    return()
+endif()
+
+# Generated output goes to the build tree, never the source tree (the stale
+# committed Doxyfile this replaced dumped HTML into doc/). /build* is gitignored.
+set(DOXYGEN_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/doc")
+
+# This is the setting that makes "infrastructure now, docs as code is touched"
+# work: EXTRACT_ALL = NO means the output contains *only* entities that carry a
+# Doxygen comment, so it starts near-empty and grows exactly as /** */ comments
+# are added. WARN_IF_UNDOCUMENTED = NO
+# keeps the build quiet about the as-yet-undocumented legacy tree instead of
+# emitting thousands of warnings.
+set(DOXYGEN_EXTRACT_ALL NO)
+set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
+
+set(DOXYGEN_RECURSIVE YES)
+set(DOXYGEN_GENERATE_HTML YES)
+set(DOXYGEN_GENERATE_LATEX NO)
+
+set(DOXYGEN_PROJECT_NAME "CODES")
+set(DOXYGEN_PROJECT_NUMBER "${PROJECT_VERSION}")
+
+# Render the README as the docs landing page.
+set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_SOURCE_DIR}/README.md")
+
+# INPUT is broad (codes/ + src/); EXTRACT_ALL = NO does the filtering. Absolute
+# paths so the inputs resolve regardless of WORKING_DIRECTORY.
+doxygen_add_docs(docs
+    "${CMAKE_SOURCE_DIR}/codes"
+    "${CMAKE_SOURCE_DIR}/src"
+    "${CMAKE_SOURCE_DIR}/README.md"
+    WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+    COMMENT "Generating CODES API documentation (Doxygen)")