1

Using macros, I've created lots of very similar matrix and vector structs (i.e: Vec1i, Vec1f, Vec2i etc.), but I'm not sure how I should document them without copy/pasting the same comment for every single struct and replacing the type and size. For example:

#define CREATE_VECTOR(TYPE, TYPE_NAME, NUM_DIMENSIONS)\
struct vec ## NUM_DIMENSIONS ## TYPE_NAME\
{\
    TYPE data[NUM_DIMENSIONS];\
};\
typedef struct vec ## NUM_DIMENSIONS ## TYPE_NAME Vec ## NUM_DIMENSIONS ## TYPE_NAME;

#define CREATE_MATRIX(TYPE, TYPE_NAME, ROWS, COLUMNS)\
struct mat ## ROWS ## x ## COLUMNS ## TYPE_NAME\
{\
    TYPE data[ROWS][COLUMNS];\
};\
typedef struct mat ## ROWS ## x ## COLUMNS ## TYPE_NAME Mat ## ROWS ## x ## COLUMNS ## TYPE_NAME;

The problem with this is that I still have to write the documentation for every vector/matrix I create:

////////////////////////////////////////////////////////////////
/// \struct Vec3i
///
/// \brief *my description*
///
/// \var Vec3i::data
///
/// \brief *member description*
///
////////////////////////////////////////////////////////////////
CREATE_VECTOR(int, i, 3);

Is it possible to document a whole collection of structs, or have doxygen automatically generate documentation for every version of the vector/matrix?

Ben Hollier
  • 585
  • 2
  • 11
  • 32
  • How is it going to generate the `*my description*` part automatically? – Cody Gray - on strike Aug 27 '17 at 17:09
  • @CodyGray there'd be generic text where the parameters of the macros can be substituted in. For example: "This is a NUM_DIMENSIONS dimensional vector which stores NUM_DIMENSIONS TYPEs" would appear as "This is a 3 dimensional vector which stores 3 ints" for a Vec3i struct – Ben Hollier Aug 27 '17 at 17:14
  • 3
    Sometimes just copying and pasting is the best way over macros. It will make the code more readable (I find your macros badly readable). The purpose is maintenance and communication to fellow programmers tasked in the future with maintaining your work. The purpose is not "how to do it as quick [and dirty] as possible". – Paul Ogilvie Aug 27 '17 at 17:18
  • @PaulOgilvie but that makes the documentation difficult to maintain, because if I want to change the wording of the descriptions, i'll need to do it approximately 16 times for every version of the struct, since i doubt there will be much uniqueness to the individual descriptions – Ben Hollier Aug 27 '17 at 17:28
  • 2
    Then best think about the best wording first? – Paul Ogilvie Aug 27 '17 at 17:30
  • 2
    See https://stackoverflow.com/questions/37284399/doxygen-single-comment-block-for-multiple-functions for some ideas – Jeff Aug 27 '17 at 17:39
  • 1
    If nothing else you can write a short script to generate a header file just for these definitions. – Jeff Aug 27 '17 at 18:27
  • Note that `NUM_DIMENSIONS` is probably a misnomer; it is more like the `VECTOR_SIZE`. Normally, number of dimensions refers to the number of subscripts; a vector is a 1D array (`vector[i]`), a matrix is a 2D array (`matrix[r][c]`), and so on. – Jonathan Leffler Aug 27 '17 at 18:31
  • 1
    Did you also have a look at commands like \copydoc? – albert Aug 28 '17 at 17:12
  • @albert it was mentioned in the accepted answer that Jeff linked. I think it's a possibility but it isn't exactly ideal since all the documentation would be identical – Ben Hollier Aug 28 '17 at 17:30

0 Answers0