Repository navigation
Conversation
fpistm
added
enhancement
fpistm
force-pushed
the
doc
branch
2 times, most recently
from
October 30, 2026 11:19
31bbd8a to
a51bc3c
Compare
Signed-off-by: Frederic Pillon <frederic.pillon@st.com>
Document the purpose, usage and configuration of each script in CI/update: - stm32variant.py, - stm32variantv2.py, - stm32cube.py, - stm32cubev2.py, - stm32wrapper.py, - stm32svd.py, - fqbn.py, - stm32api.py - stm32libraries.py. Correct the stm32variant.py description (GitHub database by default, --cube option, CUBEMX_DIRECTORY and STM32CUBECLT_PATH settings). Signed-off-by: Frederic Pillon <frederic.pillon@st.com> Assisted-by: GitHub Copilot: Claude Haiku 5.5
Review doxygen comments in headers and sources under cores/, libraries/, system/STM32* and variants/ (excluding cores/arduino/api, system/Drivers and system/Middlewares) and apply one style: - API contracts (@brief, @PARAM, @return, @note) live in headers. Functions declared in a header are documented there and their duplicate blocks are removed from the source file. - Static and source-only functions are documented directly above their definition in the .c/.cpp file. - Parameter names in header declarations now match their definitions in HardwareTimer.h, analog.h, Wire.h, VirtIO mbox_ipcc.h, Serial.h and stm32_def.h. This is a name-only change with no ABI impact. - @PARAM None is removed, since it documents no parameter. @RetVal None is removed from cores/ and libraries/ and kept only in ST-derived system/STM32* files. - Undocumented functions are documented, including HardwareTimer methods, Wire and twi helpers, SPI, EEPROM, Servo, USBDevice, Serial Uart, WSerial serialEvent hooks, pins_arduino, variant clock helpers, and assert_failed in the hal_conf_default headers. - Struct and class member docs are added in cdc_queue.h, EEPROM.h (EERef and EEPtr index) and pinmap.h (PinMap and NP). - usbd_cdc.h \defgroup entries get titles. The @file and \file names in syscalls.c and interrupt.cpp are corrected. The unnamed size parameter of operator delete in new.cpp is no longer documented with @PARAM. Doxygen (1.9.8) run over the same scope, excluding cores/arduino/api and the Drivers and Middlewares folders: "(function) ... is not documented" warnings drop from 210 to 7. Five of the remaining seven are __attribute__ misparses (aligned/used). The other two are not missing docs: HAL_FLASH_Lock is a call site in stm32_eeprom.c whose prototype lives in the excluded ST HAL headers, and stm32_interrupt_enable is documented in interrupt.h, but Doxygen cannot see that prototype under its __cplusplus guard. In USBDevice, the #ifdef blocks in usbd_cdc.h and usbd_hid_composite.h are reordered with equivalent declarations. Apart from the parameter-name fixes and that reordering, only comments changed. Signed-off-by: Frederic Pillon <frederic.pillon@st.com> Assisted-by: GitHub Copilot: Claude Haiku 5.5 Assisted-by: GitHub Copilot: Claude Sonnet 5.5 Signed-off-by: Frederic Pillon <frederic.pillon@st.com>
Point the supported boards link in README.md to the dev version of the hosted MkDocs site instead of the repository markdown file. Signed-off-by: Frederic Pillon <frederic.pillon@st.com>
Generate the Doxygen API reference of the core and publish it with each documentation version, so it is available at /dev/doxygen/, /latest/doxygen/ and /<X.Y.Z>/doxygen/. - Add doxygen/Doxyfile covering cores, libraries, system and variants, excluding cores/arduino/api, system/Drivers and system/Middlewares. Source listings are disabled to keep each published version small. __cplusplus and the HAL module macros used as guards are predefined so that classes such as HardwareTimer are documented. - Add an HTML header and version-selector.js: every Doxygen page links back to the documentation home of the same version and provides a version selector (dev, latest, releases) fed by the mike versions.json. When a page does not exist in the selected version, it falls back to the Doxygen home page, then to the documentation home page. - Add docs/hooks/doxygen.py, a MkDocs hook adding the Doxygen output to the site, or a placeholder page when it is absent so that documentation only builds still pass mkdocs build --strict. - Build the Doxygen output in docs-check.yml and publish-docs.yml before MkDocs, check that it is part of the site, and also trigger both workflows on changes to the documented sources. - Ignore doxygen/** in the Arduino, CMake and PlatformIO build workflows. - Link the reference from API.md, the home page, the Core Reference navigation and README.md. - Document the Doxygen generation, publication and version selector in Documentation-workflow.md. - Restrict the release tag pattern to a major version below 1000 in publish-docs.yml (tag validation and "latest" computation) and in the supported boards generator. The legacy date tags 2017.8.31 to 2018.1.18 matched X.Y.Z and were seen as the highest tag, so "latest" and the site default would never have moved to a new release. - Document in Documentation-workflow.md how the supported boards "Next release" labels are resolved from the release tags, and that docs/supported-boards/index.md must be regenerated and committed after a release tag. Assisted-by: GitHub Copilot: Claude Sonnet 5.5 Signed-off-by: Frederic Pillon <frederic.pillon@st.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.