doc: Add zephyr/include to the Doxygen input#10971
Open
lgirdwood wants to merge 1 commit into
Open
Conversation
lgirdwood
requested review from
dbaluta,
kv2019i,
lbetlej,
mmaka1 and
plbossart
as code owners
The Memory Allocation (alloc_api), PM Runtime (pm_runtime) and DMA (sof_dma_drivers, sof_dma_copy_func) API groups stopped appearing in the generated documentation when their headers were decoupled into zephyr/include during the RTOS split. The Doxygen INPUT still listed only src/include and xtos/include, so those Zephyr-era headers were no longer scanned and sof-docs reported "Cannot find group" for all four. Add zephyr/include to the INPUT. These headers declare exactly those four groups and no others, with no group-name overlap with xtos/include, so this recovers the missing API docs without introducing duplicates. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the SOF Doxygen configuration to scan Zephyr-split headers again, restoring API groups that disappeared from generated documentation after the RTOS split.
Changes:
- Add
zephyr/includeto the DoxygenINPUTpaths so headers under that tree are scanned. - Add/expand Doxygen comments in
module/generic.hfor module adapter APIs and related macros/types.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 11 comments.
| File | Description |
|---|---|
| src/include/sof/audio/module_adapter/module/generic.h | Adds extensive Doxygen annotations for module adapter/module APIs, macros, and enums. |
| doc/sof.doxygen.in | Extends Doxygen INPUT to include @top_srcdir@/zephyr/include for documentation generation. |
Comment on lines
+276
to
+280
| * \brief Get module heap information. | ||
| * \param mod Processing module pointer. | ||
| * \param size[out] Pointer to store heap size. | ||
| * \param start[out] Pointer to store heap start address. | ||
| */ |
Comment on lines
+649
to
+652
| * \brief Get module adapter heap usage statistics. | ||
| * \param mod Processing module pointer. | ||
| * \param hwm[out] Pointer to store high water mark. | ||
| * \return Current heap usage in bytes. |
Comment on lines
+658
to
+662
| * \brief Get module attribute (IPC3 stub). | ||
| * \param dev Component device. | ||
| * \param type Attribute type. | ||
| * \param value[out] Attribute value. | ||
| * \return -EINVAL (not supported in IPC3). |
Comment on lines
+703
to
+707
| * \param param_id Parameter ID. | ||
| * \param first_block True if first data block. | ||
| * \param last_block True if last data block. | ||
| * \param data_offset[out] Offset into configuration data. | ||
| * \param data[out] Configuration data buffer. |
Comment on lines
+791
to
+795
| * \param first_block True if first data block. | ||
| * \param last_block True if last data block. | ||
| * \param data_offset[out] Offset into configuration data. | ||
| * \param data[out] Configuration data buffer. | ||
| * \return 0 on success, negative error code on failure. |
Comment on lines
+883
to
+887
| * \brief Get hardware parameters for module adapter. | ||
| * \param dev Component device. | ||
| * \param params[out] Stream parameters to retrieve. | ||
| * \param dir Direction (input/output). | ||
| * \return 0 on success, negative error code on failure. |
Comment on lines
+892
to
+896
| * \brief Get stream position from module adapter. | ||
| * \param dev Component device. | ||
| * \param posn[out] Stream position information. | ||
| * \return 0 on success, negative error code on failure. | ||
| */ |
Comment on lines
+918
to
+922
| * \brief Get timestamp data from module adapter (Zephyr native drivers). | ||
| * \param dev Component device. | ||
| * \param tsd[out] DAI timestamp data. | ||
| * \return 0 on success, negative error code on failure. | ||
| */ |
Comment on lines
+926
to
+930
| * \brief Get timestamp data from module adapter. | ||
| * \param dev Component device. | ||
| * \param tsd[out] Timestamp data. | ||
| * \return 0 on success, negative error code on failure. | ||
| */ |
Comment on lines
+29
to
+36
| /** | ||
| * \def IS_PROCESSING_MODE_AUDIO_STREAM | ||
| * \brief Check if module uses audio stream processing mode. | ||
| * \param mod Pointer to the processing module. | ||
| * \return True if module processes audio streams, false otherwise. | ||
| * | ||
| * Helper to determine if module uses audio stream processing type. | ||
| * Needed until all modules use PROCESSING_MODE_SINK_SOURCE. |
lgirdwood
force-pushed
the
doc-add-zephyr-include
branch
from
f28a4bd to
28d6041
Compare
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.
What
Add
zephyr/includeto the DoxygenINPUTindoc/sof.doxygen.in.Why
The Memory Allocation (
alloc_api), PM Runtime (pm_runtime) and DMA(
sof_dma_drivers,sof_dma_copy_func) API doc groups stopped appearing in thegenerated documentation when their headers were decoupled into
zephyr/include/during the RTOS split. The Doxygen
INPUTstill listed onlysrc/includeandxtos/include, so those Zephyr-era headers were no longer scanned, and sof-docsreported
Cannot find groupfor all four.These headers declare exactly those four groups and no others, with no
group-name overlap with
xtos/include, so adding the directory recovers themissing API docs without introducing duplicates.
Testing
Regenerated the Doxygen XML and rebuilt sof-docs against it: all four groups now
render, and the sof-docs warning count drops from 6 to 2 (the remaining two are
a pre-existing breathe limitation, unrelated to this change).
Companion PR
Supports thesofproject/sof-docs#520, whose strict (
-W) documentation buildturns these
Cannot find groupwarnings into errors. That PR's build stays reduntil this change is merged; the two should land together.