Feature suggest: Indent option

Description

Quite a few code projects I worked on use indentation in doxygen blocks. It would be nice to have an option to do this in the extension.

Code example

The blocks I use generally looks like this:

/**
 * @brief       Print my ints
 *              One more line
 * 
 * @param[in]   The int to print
 * @param[in]   Another integer
 * @return      A number
 */
int printMyInt(int i1, int i2);

Where the total width from " * " to the start of the description is 16 characters wide, which fits most keys.

Actual result

/**
 * @brief 
 * 
 * @param i1 
 * @param i2 
 * @return int 
 */
int printMyInt(int i1, int i2);

Having an option named something like doxdocgen.generic.indentWith which pads spaces till the specified width, defaulted to 0, would address this. This would not change the behaviour to anyone who doesn’t want to use the feature. As far as I am aware padding spaces like this is allowed in Doxygen.

The reason I prefer this notation in some projects is that APIs with a lot of parameters with a lot of documentation generally get significantly more readable.

[rms95]

Hi,

While I do see the use case for the 2nd option, I can’t say I can recall a project using indentation on other places than directly after the tag. (Though I have not seen an extreme lot of projects using doxygen…)

That said, it does look like a more intuitive solution, as the template is the place where people are going to look to customize things.

-Having to maintain the general width setting as well as modifying all the other settings for one effect

Not exactly sure what you mean with the first part, but I would think that people who care about such detail, would customize the templates anyway. I would not put those indents in the default templates, leaving it as a customization option. When implementing option 2 I would go - if possible - for something like {indent:16} for an indent to width 16. That sounds much clearer to me than a global setting to set the width of {indent} blocks.

On a side node, there are two references you could use for the indent, either line start or block start:

Simple indent:

/**
 * @param       test
 */
|<------------>| // 16

Option A:

|<>| // Indent of 4 for the entire block
    /**
     * @param   test
     */
    |<-------->| // 12 from start of block, 16 from start of line

Option B:

    /**
     * @param       test
     */
    |<------------>| // 16

In the projects I worked with, I’ve always seen B, though some might think differently about this.

[rms95]

Thanks for looking into this!

For the projects I work(ed) on the tags param, tparam and return probably cover 80+% of all tags, so having automatic indentation for those sure saves a lot of work 😃