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

Question

Closed. This question needs details or clarity. It is not currently accepting answers.

---

Want to improve this question? As written, this question is lacking some of the information it needs to be answered. If the author adds details in comments, consider editing them into the question. Once there's sufficient detail to answer, vote to reopen the question.

Closed 5 months ago.

Improve this question

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?

• Greg Burghardt: I don't understand how foo is relevant or how it is used. It's a pointer to a single integer, But then your question talks about indices, axis, and dimensions. I was expecting 3 parameters to the function: one for each value. Can you edit your question to clarify the use case for the code? Example names don't give us the context needed to provide an answer.
• Doc Brown: A threedimensional array has 3 dimensions, one, two and three (or when using zero-based enumeration, zero, one and two). But in your question, it seems you call this an index, and "axis" and "dimension" seems to refer to something different, maybe some naming of the dimensions. Can you clarify this, or give a more real-worldish example? Currently, I have no idea what you want to document.

Answer 1

There is no such idiom, simply because the naming depends on the domain. If your two-dimensional array represents a spreadsheet, you'll use "row" and "column," rather than some generic names. If your three-dimensional array stores a set of coordinates of a 3D object, then you'll name them x, y, and z.

Similarly, it doesn't make sense to have an idiom to name parts of a tuple, or an idiom to name arguments of a method.