Type Definition Documentation

The documentation of type definitions, typedefs for short, is a simple yet tricky matter. Typedefs are aliases for other types and, as such, need to be well documented. Always document typedefs even if the complex type it uses is documented already.

Type Definition Comment Template

Typedefs require a simple comment explaining why they are being used and what type they are referencing.

/** Brief description with the type that is being used and why. */
typedef int t_ie;

No further explanation is needed regarding the type even if it is complex. Each complex type must be documented whereever it was defined. Doxygen connects the typedef and the complex type it uses automatically.

Type Definition Documentation Example

Correct:

1
2
3
4
5
	{
	0xcd,     /* OPCODE: INT imm8 */
	0x00,     /* imm8 data (vector to trigger) filled in at runtime */
	0xc3      /* OPCODE: RET (near) */
	};

Lines 1 and 4 name the type that is being used and with what purpose. Even if the purpose is the same, since the types are different, two comments are needed. Leaving line 3 blank not only increases readability but it also helps Doxygen link the comments to the typedefs appropriately.

Incorrect:

The comments on lines 3 and 4 offer little insight into the code’s behavior. Furthermore, they do not start with /** and end with */. Doxygen won’t add the information to the documentation nor link it properly to the complex type documentation.