Address a peculiarity in Doxygen ALIASES in docu by arwedus · Pull Request #770 · breathe-doc/breathe (original) (raw)

From our experience, verbatim txt can start right after the \rst command without another pair of newlines

This might also depend on the version of doxygen being used. That's what I meant with "better consistency". Is it important to have ^^ before \verbatim? I suspect that neither HTML nor XML would care about what column the verbatim element/tag starts on.

The initial newline avoids that you open a verbatim section on the first line of a comment, which would then go into the brief description. This breaks the doxygen output.

I have done some tests on the newline after the "embed-rst:leading-asterisk" now.
If you add it, then indeed, the following works:

/// \rst .. note:: A dog shall bark /// \endrst virtual void make_sound() { bark(); }

If you don't have the "ALIAS linebreak" at the end of the \rst alias, then this would not show up on the output.

However, the generated XML shows that this is still inconsistent:

embed:rst:leading-asterisk .. note:: A dog shall bark

See how there is no leading asterisk after the artificial linebreak? Breathe 1.32 still handles this graciously, but I guess the cleanest way is to only start on a newline after a \rst command.

However, doxygen itself apparently does not have a limitation to start content of block commands on the next line, i.e. the following fill be parsed just fine:

/// \code template /// struct SelectorImpl< /// ValueType, /// asl::EnableIfT<mops_common::IsBaseOf<ValueType, interfaces::BaseType>::value>> { /// // ... /// }; /// \endcode

So for maximum consistency, we should add the artificial line break at the end of the alias, too, as you suggested. Unless there would be cases where breathe can't handle it?