Skip to content

Commit 39f966e

Browse files
authored
Fix Doxygen documentation build error in onnxruntime_c_api.h (#27083)
# Fix Doxygen documentation build errors from recent PRs Fixes multiple Doxygen errors introduced by recent API additions that cause the nightly documentation build to fail (`WARN_AS_ERROR=YES`). ## Root Cause Analysis | Error | File | Line | Introduced By | Commit | Fix | |-------|------|------|---------------|--------|-----| | Duplicate `\addtogroup Global` | onnxruntime_c_api.h | 973 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Remove redundant group markers | | Unresolved `::SetSessionLogSeverityLevel()` | onnxruntime_c_api.h | 1065 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `OrtApi::SetSessionLogSeverityLevel` | | Unresolved `::RunOptionsSetRunLogSeverityLevel()` | onnxruntime_c_api.h | 1066 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `OrtApi::RunOptionsSetRunLogSeverityLevel` | | `<ep_name>` interpreted as HTML | onnxruntime_c_api.h | 1119 | PR #26971 - CreateEnvWithOptions API | 3874516 | Escape as `\<ep_name\>` | | `\param[in] importer` not found | onnxruntime_c_api.h | 7982 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` (macro expands to `input`) | | `\param[in] handle` not found | onnxruntime_c_api.h | 8025 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` | | `\param[in] handle` not found | onnxruntime_c_api.h | 8091 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` | | Unresolved `::CreateLoopKernel()` | onnxruntime_ep_c_api.h | 667 | PR #26927 - Control flow kernels API | 1ed8fd9 | Use `OrtEpApi::CreateLoopKernel` | | Unresolved `::CreateScanKernel()` | onnxruntime_ep_c_api.h | 710 | PR #26927 - Control flow kernels API | 1ed8fd9 | Use `OrtEpApi::CreateScanKernel` | | `<ep_name>` interpreted as HTML | onnxruntime_ep_c_api.h | 1434 | PR #26971 - CreateEnvWithOptions API | 3874516 | Escape as `\<ep_name\>` | | `\param[out] out` not found | onnxruntime_ep_c_api.h | 1440 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `\param[out] config_entries` | ## Summary by PR | PR | Issues | |----|--------| | **#26828** (c54be3c) - OrtExternalResourceImporter API for D3D12 | Duplicate Doxygen group, incorrect `\param` names for `ORT_CLASS_RELEASE` macros | | **#26927** (1ed8fd9) - Control flow kernels API | `::Method()` syntax unresolvable by Doxygen | | **#26971** (3874516) - CreateEnvWithOptions API | `::Method()` syntax, `<ep_name>` HTML interpretation, incorrect param name | ## Technical Details ### `ORT_CLASS_RELEASE` Macro Issue The `ORT_CLASS_RELEASE(X)` macro at line 164 expands to: ```cpp void(ORT_API_CALL * Release##X)(_Frees_ptr_opt_ Ort##X * input) ``` The parameter is always named `input`, but the documentation in PR #26828 used semantic names like `importer` and `handle`. Doxygen validates `\param` names against actual parameter names in the expanded code. ### Doxygen Link Resolution Doxygen 1.9.8 cannot resolve `::MethodName()` as a link to a method. The correct syntax is to qualify with the struct name: `OrtApi::MethodName`. ## Testing Verified locally with Doxygen 1.9.8 (matches CI configuration).
1 parent 5e7e7a3 commit 39f966e

File tree

2 files changed

+10
-16
lines changed

2 files changed

+10
-16
lines changed

include/onnxruntime/core/session/onnxruntime_c_api.h

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -970,10 +970,6 @@ typedef OrtStatus*(ORT_API_CALL* RegisterCustomOpsFn)(OrtSessionOptions* options
970970
*/
971971
typedef void (*RunAsyncCallbackFn)(void* user_data, OrtValue** outputs, size_t num_outputs, OrtStatusPtr status);
972972

973-
/** \addtogroup Global
974-
* @{
975-
*/
976-
977973
/** \brief External memory handle type for importing GPU resources.
978974
*
979975
* \todo Add OPAQUE_WIN32 for Windows Vulkan-specific memory handles
@@ -1041,8 +1037,6 @@ typedef struct OrtExternalTensorDescriptor {
10411037
Enables multiple tensors from the same imported memory handle. */
10421038
} OrtExternalTensorDescriptor;
10431039

1044-
/// @}
1045-
10461040
/*
10471041
* Public enum for compiled model compatibility across EPs.
10481042
*/
@@ -1068,8 +1062,8 @@ typedef struct OrtEnvCreationOptions {
10681062
* \note Logging messages which are less severe than the `logging_severity_level` are not emitted.
10691063
*
10701064
* \note Serves as the default logging severity level for session creation and runs.
1071-
* Use ::SetSessionLogSeverityLevel() to set a logging severity level for the creation of specific session.
1072-
* Use ::RunOptionsSetRunLogSeverityLevel() to set a logging severity level for a specific session run.
1065+
* Use OrtApi::SetSessionLogSeverityLevel to set a logging severity level for the creation of specific session.
1066+
* Use OrtApi::RunOptionsSetRunLogSeverityLevel to set a logging severity level for a specific session run.
10731067
*
10741068
* \since Version 1.24.
10751069
*/
@@ -1122,7 +1116,7 @@ typedef struct OrtEnvCreationOptions {
11221116
* \note Refer to onnxruntime_env_config_keys.h for common config entry keys and their supported values.
11231117
*
11241118
* \note An application provides environment-level configuration options for execution provider libraries by
1125-
* using keys with the prefix 'ep_factory.<ep_name>.'. Ex: the key 'ep_factory.my_ep.some_ep_key' represents
1119+
* using keys with the prefix 'ep_factory.\\<ep_name\\>.'. Ex: the key 'ep_factory.my_ep.some_ep_key' represents
11261120
* a key named 'some_ep_key' that is meant to be consumed by an execution provider named 'my_ep'. Refer to
11271121
* the specific execution provider's documentation for valid keys and values.
11281122
*
@@ -7985,7 +7979,7 @@ struct OrtInteropApi {
79857979

79867980
/** \brief Release an OrtExternalResourceImporter instance.
79877981
*
7988-
* \param[in] importer The OrtExternalResourceImporter instance to release. May be nullptr.
7982+
* \param[in] input The OrtExternalResourceImporter instance to release. May be nullptr.
79897983
*
79907984
* \since Version 1.24.
79917985
*/
@@ -8028,7 +8022,7 @@ struct OrtInteropApi {
80288022

80298023
/** \brief Release an OrtExternalMemoryHandle instance.
80308024
*
8031-
* \param[in] handle The OrtExternalMemoryHandle instance to release. May be nullptr.
8025+
* \param[in] input The OrtExternalMemoryHandle instance to release. May be nullptr.
80328026
*
80338027
* \since Version 1.24.
80348028
*/
@@ -8094,7 +8088,7 @@ struct OrtInteropApi {
80948088

80958089
/** \brief Release an OrtExternalSemaphoreHandle instance.
80968090
*
8097-
* \param[in] handle The OrtExternalSemaphoreHandle instance to release. May be nullptr.
8091+
* \param[in] input The OrtExternalSemaphoreHandle instance to release. May be nullptr.
80988092
*
80998093
* \since Version 1.24.
81008094
*/

include/onnxruntime/core/session/onnxruntime_ep_c_api.h

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -664,7 +664,7 @@ struct OrtLoopKernelHelper;
664664
typedef struct OrtLoopKernelHelper OrtLoopKernelHelper;
665665

666666
/**
667-
* \brief Contains helper functions for a Loop OrtKernelImpl created via ::CreateLoopKernel().
667+
* \brief Contains helper functions for a Loop OrtKernelImpl created via OrtEpApi::CreateLoopKernel.
668668
* \since Version 1.24.
669669
*/
670670
struct OrtLoopKernelHelper {
@@ -707,7 +707,7 @@ struct OrtScanKernelHelper;
707707
typedef struct OrtScanKernelHelper OrtScanKernelHelper;
708708

709709
/**
710-
* \brief Contains helper functions for a Scan OrtKernelImpl created via ::CreateScanKernel().
710+
* \brief Contains helper functions for a Scan OrtKernelImpl created via OrtEpApi::CreateScanKernel.
711711
* \since Version 1.24.
712712
*/
713713
struct OrtScanKernelHelper {
@@ -1431,13 +1431,13 @@ struct OrtEpApi {
14311431
/** \brief Gets a new OrtKeyValuePairs instance containing a copy of all configuration entries set on the environment.
14321432
*
14331433
* \note An application provides environment-level configuration options for execution provider libraries by
1434-
* using keys with the prefix 'ep_factory.<ep_name>.'. Ex: the key 'ep_factory.my_ep.some_ep_key' represents
1434+
* using keys with the prefix 'ep_factory.\\<ep_name\\>.'. Ex: the key 'ep_factory.my_ep.some_ep_key' represents
14351435
* a key named 'some_ep_key' that is meant to be consumed by an execution provider named 'my_ep'. Refer to
14361436
* the specific execution provider's documentation for valid keys and values.
14371437
*
14381438
* \note Refer to onnxruntime_env_config_keys.h for common configuration entry keys and their supported values.
14391439
*
1440-
* \param[out] out Output parameter set to the OrtKeyValuePairs instance containing all configuration entries.
1440+
* \param[out] config_entries Output parameter set to the OrtKeyValuePairs instance containing all configuration entries.
14411441
* Must be released via OrtApi::ReleaseKeyValuePairs.
14421442
*
14431443
* \snippet{doc} snippets.dox OrtStatus Return Value

0 commit comments

Comments
 (0)