Newer versions of Doxygen not seem to be compatible with DoxyDoxygen default settings

[20Tauri]

An interesting report from Pieter, I want to share with you:

Consider this example:

    /**
     * @brief      Get the foo.
     *
     *             This function returns the foo, which is a very complicated thing
     *             for which a brief description is not sufficient.
     *
     * @return     Returns the foo.
     */
    int foo();

This is how DoxyDoxygen formats things with its default settings ("doxygen_paragraph_prefix": "\t"). It worked fine with doxygen 1.6.1. But doxygen 1.8.16 interprets the long description as a code fragment because it is indented by more than 4 spaces. So it renders the @brief and @return parts fine, but the detailed description is formatted using a fixed-width font and with hard-wrapped lines.

If I set “doxygen_paragraph_prefix” to “ ” (i.e. a space), I get this:

    /**
     * @brief Get the foo.
     *
     * This function returns the foo, which is a very complicated thing for
     * which a brief description is not sufficient.
     *
     * @return Returns the foo.
     */
    int foo();

This works fine in both versions, but I don’t like how it looks in the code.
Esp. if there are many @param descriptions it doesn’t give a clear overview, so I liked the “\t” setting much more.

It would be good if you could keep the “\t” prefix for everything except a detailed description that doesn’t have a @details tag, like this:

    /**
     * @brief      Get the foo.
     *
     * This function returns the foo, which is a very complicated thing for
     * which a brief description is not sufficient.
     *
     * @return     Returns the foo.
     */
    int foo();

Right now it seems setting “doxygen_paragraph_prefix” to “\t” has no use for the newer versions of doxygen.

My second suggestion was to have a setting that tells the package to respect my indentation on updating. For example, if I set “doxygen_paragraph_prefix” to “\t”, I get the first example by default. If I then manually remove the unwanted indent, I get this

    /**
     * @brief      Get the foo.
     *
     * This function returns the foo, which is a very complicated thing
     * for which a brief description is not sufficient.
     *
     * @return     Returns the foo.
     */
    int foo();

That’s better, but now my lines aren’t wrapped correctly.
I may want to add some text and have it auto-wrapped.
But if I press alt-Q to make it re-wrap the lines, it will also put back the indentation the way it was before.
It would be good to have an option to re-wrap lines, add missing @param’s, etc., but leave the indentation of existing documentation as is.
That way, if DoxyDoxygen doesn’t exactly do what you want, it’s easier to work around it by manually fixing things here and there.
Currently the only way I can keep things as in the wanted example (the 3rd one), is by first manually making them that way and then not touching alt-Q anymore.

My current workaround is to change DoxyDoxygen’s shortcut to alt-D, and keep alt-Q for simpler wrapping packages.
That way I can use alt-D to get a default doxygen comment, then modify it and use alt-Q for wrapping my lines without changing anything else.

Best regards,

Pieter

[20Tauri]

The best way to deal with this problem (if it's not a but in Doxygen is simply to remove the @brief tag.

To generate a brief description without the @brief tag, simply replace @brief with @_brief in the "block_layout" parameter (DoxyDoxygen settings)

If confirmed, t can be the new DoxyDoxygen default settings in future.

Also seem that the defaut setting with Python (generate comments) is not what you prefer (generate docsrings). I'm interested n your feelling about those default settngs