Is there an idiom for specifying axes and dimensions of array(-like) parameters?

Many programming languages have functions which take a parameter which is a potentially-multi-dimensional array, where the number of axes and the dimension in each axis is not specified in code. This includes, in particular, any language where a raw pointer can be passed to a function, such as C and C++. When documenting such a function, it stands to reason to document - when possible - the explicit or implicit number of axis, what each axis is called or signifies, and what the dimensions are in each axis, as a function of the other parameters, or known constants etc. (provided that these dimensions can be described apriori). I was wondering, if there is some common format or other documentation approach to doing so. I often find myself adding bits of doxygen such as the following: /** -- snip -- * * @note foo axes & dimensions (major to minor): * * | Index | Axis | Dimension | * | :---- | :------ | :--------- | * | 0 | bar | ?? | * | 1 | X | NX | * | 2 | Y | NumLines | * -- snip -- / void func(int foo); where the "snip" is other doxygen comment text. But this is not picked up on by the Doxygen processor, nor is it "strongly" tied to the foo parameter. Can I replace this with something more useful?

Mar 25, 2025 - 19:00

Many programming languages have functions which take a parameter which is a potentially-multi-dimensional array, where the number of axes and the dimension in each axis is not specified in code. This includes, in particular, any language where a raw pointer can be passed to a function, such as C and C++.

When documenting such a function, it stands to reason to document - when possible - the explicit or implicit number of axis, what each axis is called or signifies, and what the dimensions are in each axis, as a function of the other parameters, or known constants etc. (provided that these dimensions can be described apriori).

I was wondering, if there is some common format or other documentation approach to doing so. I often find myself adding bits of doxygen such as the following:

/**
-- snip --
 *
 * @note foo axes & dimensions (major to minor):
 *
 *   | Index | Axis    | Dimension  |
 *   | :---- | :------ | :--------- |
 *   | 0     | bar     | ??         |
 *   | 1     | X       | NX         |
 *   | 2     | Y       | NumLines   |
 *
-- snip --
 */
void func(int* foo);

where the "snip" is other doxygen comment text. But this is not picked up on by the Doxygen processor, nor is it "strongly" tied to the foo parameter. Can I replace this with something more useful?