From 1c98a9f50d4fa98a5e022541689dd942618b350f Mon Sep 17 00:00:00 2001
From: Joffrey Dorville <jdorville@anl.gov>
Date: Fri, 29 May 2026 13:02:01 -0500
Subject: [PATCH] Use case example

---
 docs/source/capi/index.rst | 43 +++++++++-----------------------------
 include/openmc/capi.h      | 27 ++++++++++++++++++++++++
 2 files changed, 37 insertions(+), 33 deletions(-)

diff --git a/docs/source/capi/index.rst b/docs/source/capi/index.rst
index 1777e795ad..f47d7065a0 100644
--- a/docs/source/capi/index.rst
+++ b/docs/source/capi/index.rst
@@ -46,43 +46,20 @@ Type Definitions
 Functions
 ---------
 
-.. c:function:: int openmc_calculate_volumes()
+..
+   Once documentation is complete in capi.h, use:
+   .. doxygenfile:: capi.h
+   to populate this documentation without using
+   .. doxygenfunction::
+   for every functions.
 
-   Run a stochastic volume calculation
+.. doxygenfunction:: openmc_calculate_volumes
 
-   :return: Return status (negative if an error occurred)
-   :rtype: int
+.. doxygenfunction:: openmc_cell_get_fill
 
-.. c:function:: int openmc_cell_get_fill(int32_t index, int* type, int32_t** indices, int32_t* n)
+.. doxygenfunction:: int openmc_cell_get_id
 
-   Get the fill for a cell
-
-   :param int32_t index: Index in the cells array
-   :param int* type: Type of the fill
-   :param int32_t** indices: Array of material indices for cell
-   :param int32_t* n: Length of indices array
-   :return: Return status (negative if an error occurred)
-   :rtype: int
-
-.. c:function:: int openmc_cell_get_id(int32_t index, int32_t* id)
-
-   Get the ID of a cell
-
-   :param int32_t index: Index in the cells array
-   :param int32_t* id: ID of the cell
-   :return: Return status (negative if an error occurred)
-   :rtype: int
-
-.. c:function:: int openmc_cell_get_temperature(int32_t index, const int32_t* instance, double* T)
-
-   Get the temperature of a cell
-
-   :param int32_t index: Index in the cells array
-   :param int32_t* instance: Which instance of the cell. If a null pointer is passed, the temperature
-                             of the first instance is returned.
-   :param double* T: temperature of the cell
-   :return: Return status (negative if an error occurred)
-   :rtype: int
+.. doxygenfunction:: openmc_cell_get_temperature
 
 .. c:function:: int openmc_cell_get_density(int32_t index, const int32_t* instance, double* density)
 
diff --git a/include/openmc/capi.h b/include/openmc/capi.h
index 911654d318..f8b13ae582 100644
--- a/include/openmc/capi.h
+++ b/include/openmc/capi.h
@@ -9,14 +9,41 @@
 extern "C" {
 #endif
 
+//! Run a stochastic volume calculation
+//
+//! \return Status (negative if an error occurred)
 int openmc_calculate_volumes();
+
 int openmc_cell_filter_get_bins(
   int32_t index, const int32_t** cells, int32_t* n);
+
+//! Get the fill for a cell
+//
+//! \param index Index in the cells array
+//! \param type Type of the fill
+//! \param indices Array of material indices for cell
+//! \param n Length of indices array
+//! \return Status (negative if an error occurred)
 int openmc_cell_get_fill(
   int32_t index, int* type, int32_t** indices, int32_t* n);
+
+//! Get the ID of a cell
+//
+//! \param index Index in the cells array
+//! \param id ID of the cell
+//! \return Status (negative if an error occurred)
 int openmc_cell_get_id(int32_t index, int32_t* id);
+
+//! Get the temperature of a cell
+//
+//! \param index Index in the cells array
+//! \param instance Which instance of the cell. If a null pointer is
+//!                 passed, the temperature of the first instance is returned.
+//! \param T temperature of the cell
+//!\return Status (negative if an error occurred)
 int openmc_cell_get_temperature(
   int32_t index, const int32_t* instance, double* T);
+
 int openmc_cell_get_density(
   int32_t index, const int32_t* instance, double* rho);
 int openmc_cell_get_translation(int32_t index, double xyz[]);