Support an opt-in alternative semantics for multi-paragraph elements

[eyalroz]

This expands on a discussion in #9786 .

When I write:

/**
 * @note The quick brown fox jumps over the lazy dog. The quick brown fox jumps 
 * over the lazy dog. The quick brown fox jumps over the lazy dog. 
 *
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 
 * incididunt ut labore et dolore magna aliqua.
 **/

I would like Doxygen to interpret this "Lorem" paragraph as a second paragraph that's part of the @note element. And when I write

/**
 * @note The quick brown fox jumps over the lazy dog. The quick brown fox jumps 
 * over the lazy dog. The quick brown fox jumps over the lazy dog. 
 *
 * @note Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 
 * incididunt ut labore et dolore magna aliqua. 
 **/

I expect this to be interpreted as two distinct notes. However, this is not how Doyxgen behaves: For the first snippet, the Lorem paragraph will be rendered outside the note; for the second snippet, we would get one note with the Lorem paragraph in it.

This is not a new issue - doxygen has behaved like this for a long time (or forever). And obviously, existing documentation often relies on the existing behavior.

But - I would like to have a configuration option to get doxygen to behave the way I described w.r.t. separating items and paragraphs.

---

Note: I know that we can currently achieve separation of @note-like element using @parblock, e.g. something like:

/**
 * @parblock
 * @note Note1 goes here
 * @endparblock
 * @parblock
 * @note Note2 goes here
 * @endparblock
 */

but this is inconvenient both to write and to read.

[albert-github]

We have in this issue 2 problems mentioned:

1. when does the @note end / how to prevent to have to write multiple times the @note command
2. unwanted joining of multiple @note

The problem is that there is no @endnote command so there is no real possibility other than defining the end of a note as it is done now.

One could write now:

/**
 * @note
 * @parblock
 * The quick brown fox jumps over the lazy dog. The quick brown fox jumps
 * over the lazy dog. The quick brown fox jumps over the lazy dog.
 *
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
 * incididunt ut labore et dolore magna aliqua.
 * @endparblock
 **/

this would already give the required effect for multiple paragraphs in one note and also clearly indicated this.
An alternative might be to define an option with the @note like block that would also require a command @endnote to signal the end of the note. The command @endnote would only be allowed when the note has been started with @note{block} so this would look like:

/**
 * @note{block}
 * The quick brown fox jumps over the lazy dog. The quick brown fox jumps
 * over the lazy dog. The quick brown fox jumps over the lazy dog.
 *
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
 * incididunt ut labore et dolore magna aliqua.
 * @endnote
 **/

Would be a bit complicated and confusing as the requirement of the @endnote only would be allowed when the option block is used. A Better alternative here would be to have 2 new commands like @noteblock and @endnoteblock), this would not only apply to the @note command but also to a number of other commands (like @bug, @todo etc).

An option regarding the merging of the multiple subsequent notes might be to define a nomerge option with the @note command so for the "Lorem ipsum dolor sit" one has to write:

/**
 * @note The quick brown fox jumps over the lazy dog. The quick brown fox jumps 
 * over the lazy dog. The quick brown fox jumps over the lazy dog. 
 *
 * @note{nomerge} Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 
 * incididunt ut labore et dolore magna aliqua. 
 **/

this would not only apply to the @note command but also to a number of other commands (like @bug, @todo etc).
So this would be an enhancement.

However there is in my opinion already a working alternative:

/**
 * @note The quick brown fox jumps over the lazy dog. The quick brown fox jumps 
 * over the lazy dog. The quick brown fox jumps over the lazy dog. 
 * <p></p>
 * @note Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor 
 * incididunt ut labore et dolore magna aliqua. 
 **/

So all in all I think there are already enough possibilities to solve this issue (and the <p></p> is far less intrusive and disturbing than the multiple @parblock / @endparblock).

The changing of the current meaning of the end of a `@note is in my opinion a no go as this would break (a lot of) existing projects.

[albert-github]

Small note regarding the @noteblock command, this is already possible by defining:

ALIASES  = noteblock="@note @parblock"
ALIASES += endnoteblock="@endparblock"

and the source would look like:

/**
 * @noteblock The quick brown fox jumps over the lazy dog. The quick brown fox jumps
 * over the lazy dog. The quick brown fox jumps over the lazy dog.
 *
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
 * incididunt ut labore et dolore magna aliqua.
 * @endnoteblock
 **/

[eyalroz]

The problem is that there is no @endnote command

That's not the problem - it's a possible solution, or part-of-a-solution, for the problem. But - having to insert @endnote's increases verbosity. I would like other commands - like another @note, or commands which are not parts of a note (like @brief or @return) to implicitly end the note. And you could still introduce @endnote for explicit forcing.

[albert-github]

Btw. what is @output never heard of that command.

[eyalroz]

@albert-github : Sorry, I meant @return.