Doxygen command paragraph (hanging) indentation limitations?

1
votes

Are there any limits for how much indentation can be used on multi-line (paragraph) commands?

Consider a typical use-case of @details in the context of a function:

/**
 * @brief Do foo.
 * @details Lorem ipsum dolor sit amet, mentitum rationibus nec an.
 *          Usu magna eirmod et, aperiri discere volumus pri ex.
 *
 *          Te pro alii vidit, cu nonumes mediocritatem duo.
 *          Paulo detracto tincidunt id vim, ad has oblique percipit.
 *
 * @tparam T The argument type.
 * @param param1 The first parameter.
 * @param param2 The second parameter.
 * @return The return value.
 */
 template< typename T >
 inline
 T foo( T const& param1, T const& param2 );

The long @details paragraphs have to be wrapped, which leads to the question of are there any restrictions on this indentation?

I know that Doxygen uses Markdown, which has specific indentation restrictions / uses, such as the "4 space indentation" for codeblocks. Would the indentation above confuse or conflict in cases where I wanted to insert code?

More generally, are there other indentation uses and possible conflicts I'm unaware of?

@thomas-matthews, this is a question about technical limitations, not aesthetic style.

1
c++doxygenindentationrestrictions
@thomas-matthews, this is a question about technical limitations, not aesthetic style. - Charles L Wilcox
@thomas-matthews, Also, "... asked before and already has an answer." is incorrect; no one's addressed the other question yet. - Charles L Wilcox
To whomever asked to reopen this: Thank you. - Charles L Wilcox
I don't have a definitive answer but I would advise against this indentation as, in my experience, it does not take much to confuse the interpreter, especially with the Markdown support enabled. For aesthetics, consider enabling JAVADOC_AUTOBRIEF. this would remove the need for any indentation in the source comment. - Cheeseminer

1 Answers

1
votes

Very crude suggestion, but this is what worked for me -

/**
 * @brief Do foo.
 * @details Lorem ipsum dolor sit amet, mentitum rationibus nec an.
 *
 * &nbsp; &nbsp; &nbsp; &nbsp; Usu magna eirmod et, aperiri discere volumus pri ex.
 * &nbsp; &nbsp; &nbsp; &nbsp; 
 * &nbsp; &nbsp; &nbsp; &nbsp; Te pro alii vidit, cu nonumes mediocritatem duo.
 * &nbsp; &nbsp; &nbsp; &nbsp; Paulo detracto tincidunt id vim, ad has oblique percipit.
 *
 * @tparam T The argument type.
 * @param param1 The first parameter.
 * @param param2 The second parameter.
 * @return The return value.
 */