Version at 0.2.0: complete the wishlist, document it, gate the docs

Closes what was left of TODO.md sections 1, 2 and 3, and rewrites that
file to hold outstanding items only.

The API break gets a minor bump, because pre-1.0 the soname carries
MAJOR.MINOR and 0.1 and 0.2 are therefore different ABIs. Five
signatures changed and the ato* contract with them; UPGRADING.md is new
and lists every one, with the before/after for the cases the compiler
cannot warn about.

Section 3.1 is finished: reallocarray with the multiplication checked,
aligned_alloc and posix_memalign, asprintf/vasprintf, scanf/vscanf.
Four functions on that list are deliberately absent rather than missing
-- sprintf, strtok, setbuf and perror -- and TODO.md now says which and
why, so nobody adds them thinking they were forgotten.

Section 1.9, the cross-cutting tests:

  tests/test_pool.c    drives every failure path AKERR_MAX_ARRAY_ERROR
                       + 10 times and checks the pool after each round,
                       because a wrapper that leaks a slot fails a
                       hundred calls later in unrelated code. It also
                       asserts that each error names the function and
                       file it was raised from, which is what catches a
                       FAIL that migrates into a helper during a
                       refactor: status right, message right, origin
                       quietly lying.
  tests/negative/      two sources that must FAIL to compile, built with
                       -Werror and registered WILL_FAIL. AKERR_NOIGNORE
                       and the format attributes are enforced by the
                       compiler and by nothing else; drop either and
                       every ordinary test still passes.

Thread safety is answered rather than tested: the library is not
thread-safe and cannot be made so from here, because libakerror's error
pool is an unlocked process-global array. README.md says so plainly and
TODO.md carries it as the item blocking any future pthread wrappers.

Doxygen is configured and gated. All 147 public functions have @brief,
a @param each, @throws per status and @return; EXTRACT_ALL is off and
WARN_NO_PARAMDOC on, so `cmake --build build --target docs` fails on an
undocumented entity. It ran to 0 warnings. The Doxyfile carries no
version -- cmake/RunDoxygen.cmake feeds PROJECT_NUMBER in from
project(), so that stays the one place a version is written.

CI now builds against the submodule it pins instead of also installing
libakerror@main and never linking it, adds -Werror, and gains a
sanitizer job. The pre-push hook matches, and runs the docs check too.

Coverage: 99.5% of lines (1643/1651), 100% of functions (147/147). The
eight uncovered lines are each uncovered on purpose and TODO.md says
which and why.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CMakeLists.txt

@@ -4,10 +4,20 @@ cmake_minimum_required(VERSION 3.10)
 # shared library's VERSION/SOVERSION, the Version: field in akstdlib.pc, and
 # akstdlibConfigVersion.cmake. Nothing else should spell a version number.
 #
-# 0.x on purpose: TODO.md section 2.1 still records four confirmed defects whose
-# fixes change documented behaviour (aksl_atoi's contract, aksl_realpath's
-# signature), so this library is not promising a stable API yet.
-project(akstdlib VERSION 0.1.0 LANGUAGES C)
+# 0.2.0, and the minor bump is an ABI break on purpose. Fixing the confirmed
+# defects in TODO.md 2.1 changed documented behaviour and, in five places,
+# signatures:
+#
+#   aksl_realpath      takes the destination's length; aksl_realpath_alloc is new
+#   aksl_list_pop      takes the head by reference
+#   aksl_tree_iterate  lost its `queue` parameter
+#   aksl_fread/fwrite  take a required transferred-count out-param
+#   aksl_sprintf       is gone; aksl_snprintf replaces it
+#
+# plus the ato* family, which now reports a bad conversion rather than returning
+# 0. Pre-1.0 the soname is MAJOR.MINOR, so 0.1 and 0.2 are different ABIs and a
+# consumer built against 0.1 will not silently load this. See UPGRADING.md.
+project(akstdlib VERSION 0.2.0 LANGUAGES C)
 
 # The granularity at which the ABI is allowed to break, and therefore the
 # soname: libakstdlib.so.0.1. Pre-1.0 that is MAJOR.MINOR, because a 0.x library
@@ -302,6 +312,7 @@ set(AKSL_TESTS
     linkedlist
     memory
     path
+    pool
     status_registry
     strbuf
     stream
@@ -339,6 +350,39 @@ foreach(_test IN LISTS AKSL_TESTS AKSL_WILL_FAIL_TESTS AKSL_KNOWN_FAILING_TESTS)
   list(APPEND AKSL_TEST_TARGETS test_${_test})
 endforeach()
 
+# Negative compile tests -- TODO.md 1.3 and 1.9.
+#
+# Two properties of this library are enforced by the compiler and by nothing
+# else: AKERR_NOIGNORE makes discarding a returned error context an error, and
+# AKSL_PRINTF_FORMAT restores the format/argument checking a caller loses by
+# going through a variadic wrapper. Both are attributes on declarations in
+# include/akstdlib.h. If either is dropped in a refactor, every test still
+# passes, the library still builds, and nothing looks wrong -- the guarantee just
+# quietly stops existing.
+#
+# So each is asserted by a source file that must *fail* to compile. The target
+# is EXCLUDE_FROM_ALL and built with -Werror; the CTest entry runs that build and
+# is marked WILL_FAIL, so a successful compile fails the suite.
+#
+# Only where the compiler supports the attributes at all -- elsewhere
+# AKSL_PRINTF_FORMAT expands to nothing and the file would compile correctly.
+if(CMAKE_C_COMPILER_ID MATCHES "^(GNU|Clang|AppleClang)$")
+  foreach(_neg noignore format_mismatch)
+    add_executable(negative_${_neg} EXCLUDE_FROM_ALL tests/negative/${_neg}.c)
+    target_link_libraries(negative_${_neg} PRIVATE akstdlib)
+    target_compile_options(negative_${_neg} PRIVATE -Werror)
+    add_test(NAME negative_${_neg}
+             COMMAND ${CMAKE_COMMAND} --build ${CMAKE_CURRENT_BINARY_DIR}
+                     --target negative_${_neg})
+    set_tests_properties(negative_${_neg} PROPERTIES
+      WILL_FAIL TRUE
+      TIMEOUT 120
+      # These invoke the build system, so they must not run while another build
+      # of the same tree is in flight.
+      RUN_SERIAL TRUE)
+  endforeach()
+endif()
+
 # tests/test_memory.c asks for SIZE_MAX/2 bytes to check that a refused
 # allocation reports ENOMEM and leaves *dst NULL. Plain malloc returns NULL and
 # sets ENOMEM, which is the case under test; ASan's allocator instead treats a
@@ -445,6 +489,40 @@ elseif(AKSL_COVERAGE)
                   "(scripts/coverage.py) will not be wired into CTest")
 endif()
 
+# API documentation:
+#   cmake --build build --target docs
+#
+# The Doxyfile carries no PROJECT_NUMBER. The version lives in exactly one place
+# -- the project() call at the top of this file -- and a version written into the
+# Doxyfile as well would be a second place to forget. Doxygen reads its
+# configuration from stdin when given "-", so the number is appended on the way
+# past and the checked-in file stays version-free.
+#
+# WARN_IF_UNDOCUMENTED and WARN_NO_PARAMDOC are both on, and EXTRACT_ALL is off:
+# an undocumented function is a warning rather than a silently empty page. The
+# target fails if the log is non-empty, which is what makes "documented" a
+# property the build checks rather than an impression.
+find_program(AKSL_DOXYGEN doxygen)
+if(AKSL_DOXYGEN)
+  if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
+    set(AKSL_DOCS_TARGET docs)
+  else()
+    set(AKSL_DOCS_TARGET akstdlib_docs)
+  endif()
+  add_custom_target(${AKSL_DOCS_TARGET}
+    COMMAND ${CMAKE_COMMAND} -E echo
+            "Generating API documentation for akstdlib ${PROJECT_VERSION}"
+    COMMAND ${CMAKE_COMMAND}
+            -DAKSL_DOXYGEN=${AKSL_DOXYGEN}
+            -DAKSL_SOURCE_DIR=${CMAKE_CURRENT_SOURCE_DIR}
+            -DAKSL_VERSION=${PROJECT_VERSION}
+            -P ${CMAKE_CURRENT_SOURCE_DIR}/cmake/RunDoxygen.cmake
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    USES_TERMINAL
+    COMMENT "Running doxygen"
+  )
+endif()
+
 # Mutation testing: break the library in small ways and confirm the test suite
 # notices. This is a meta-check on the tests themselves, and it rebuilds and
 # re-runs the whole suite once per mutant, so it is a manual target rather than