From 2623ae718f21fe76958783c249569e2f798689c9 Mon Sep 17 00:00:00 2001 From: Dennis Park Date: Mon, 3 Aug 2026 14:16:13 +0900 Subject: [PATCH] docs: link the API reference from the README and back again The reference was only reachable by typing /api/ onto the project page. The README - which is that page - now carries a badge and a line under it, and its API reference section leads with the published URL rather than with instructions for building a local copy. The reference had no way back either. Its main page now links to the project page, the repository and the samples, and points at "Topics" rather than "Modules", which is what the tab has been called since Doxygen 1.10. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 15 ++++++++++++--- doc/README.md | 4 ++++ src/libcmutils.h | 15 ++++++++++++--- 3 files changed, 28 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5a3a610..63c6aef 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,10 @@ A multi-platform C99 utility library that exposes common building blocks — col [![Language: C99](https://img.shields.io/badge/Language-C99-blue.svg)](https://en.wikipedia.org/wiki/C99) [![Build System: CMake](https://img.shields.io/badge/Build-CMake%20%E2%89%A5%203.10-064F8C.svg)](https://cmake.org/) [![Platforms](https://img.shields.io/badge/Platforms-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)](#requirements) +[![API reference](https://img.shields.io/badge/docs-API%20reference-brightgreen.svg)](https://xcomart.github.io/libcmutils/api/) + +📖 **[API reference](https://xcomart.github.io/libcmutils/api/)** — every type and method, grouped by +subject. This page is the guided tour; that one is the lookup. --- @@ -1116,14 +1120,19 @@ of them bind ports or reach the network. ## API reference -The sections above are prose. The generated reference is the same API organized for lookup — grouped -by subject, built from the doc comments in `src/libcmutils.h`: +**** + +The sections above are prose. The reference is the same API organized for lookup — every type and +method grouped into eighteen subjects, generated from the doc comments in `src/libcmutils.h` and +rebuilt on every push that touches them. + +To build it locally instead: ```bash cd doc && doxygen # or: cmake --build build --target docs ``` -Open `doc/html/index.html`. See [doc/README.md](doc/README.md) for what the topics contain. +That writes `doc/html/index.html`. See [doc/README.md](doc/README.md) for what the topics contain. ## Project structure diff --git a/doc/README.md b/doc/README.md index 8deabcf..39af739 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,5 +1,9 @@ # API reference +**Published at **, rebuilt by the +`Docs` workflow on every push that touches the header, this directory, the +README or the Jekyll config. + The reference is generated from the doc comments in [`src/libcmutils.h`](../src/libcmutils.h), which is the whole public API — the `.c` files are implementation and are deliberately left out. diff --git a/src/libcmutils.h b/src/libcmutils.h index 2575613..196d24a 100644 --- a/src/libcmutils.h +++ b/src/libcmutils.h @@ -73,9 +73,18 @@ SOFTWARE. * * @section mp_where Where to look * - * The Modules list groups the API by subject. The project README - * covers the same ground in prose, and @c samples/ holds one annotated - * program per subject. + * Topics, in the bar above, groups the API by subject - start there + * if you know roughly what you need. Data Structures lists the object + * types, and the search box finds anything by name. + * + * Elsewhere: + * + * - Project page - the + * same API in prose, with the reasoning behind the conventions. + * - Repository - source, + * issues and releases. + * - + * Samples - one annotated, runnable program per subject. */ #ifndef LIBCMUTILS_H__