Glitch with the \return command in member function lists

[gennaroprota]

Hi again,

this is basically the same screenshot I attached to the previous issue report:

It seems (see the documentation of max(), min() and next()) that DocsForge picks up the \return paragraph here, including the command itself without the leading backslash. Doxygen emits the following, instead:

I'm not sure that I'm also not doing anything wrong here. If so, please tell me.

Cheers!

[erez-o]

It's by design.

Docsforge always tries to get a brief description. It uses the same concept as java and other languages do on their api docs - the first row should always be the brief description. There's no brief vs detailed description. Only if you use doxygen's \brief command docsforge will use it and not extract the first row of the detailed description.

So in your case, max() had no brief description, only detailed description with return paragraph and it was used as a brief description for the class page.

I think that if you look at max(), min() and next(), having any description is better for the naive user than leaving it blank.

[gennaroprota]

Aha. I see that Doxygen does extract the docs for operator ()(), though. Perhaps it does so only when no special command, such as \return is used? My problem with the DocsForge output is not that it contains some description but the fact that it replaces "\return" with "Return" and leaves the rest intact; so you get something like "Return A value...", which is wrong both in grammar and capitalization. Is there something I or you can do to avoid this, other than adding \brief descriptions or avoiding \return?

[erez-o]

You should definitely keep using \return and not be forced to use \brief. Moreover, docsforge does it automatically for any \par. docsforge should fix this.

The problem is the capitalization - I don't want to turn the first letter to lower case because it's error prone - acronyms or even if first word is a parameter or class name that begins with a capital case.

what about adding a colon? changing "Return" -> "Return:" I'm also fine with changing all of doxygen's special paragraphs to plural form.

I think "Returns: A value..." looks great.

Are you good with this solution?

[erez-o]

Fixed not yet released. If no \brief, the algorithm will try to use the the first paragraph or the first Return section. For example, a Parameters section or a Warning section will be skipped. As described, the result in your case will be "Returns: A value..."

[gennaroprota]

Great, thanks!

[erez-o]

Released version 3.4.21, check https://breeze.docsforge.com/master/api/breeze/entropy_source/

[gennaroprota]

Great! I've just noticed that, if the \return paragraph consists of one sentence with a final period, the period is kept. But if it consists of multiple sentences, only the first is taken, and the final period omitted. Would it be possible to not remove the period? (I haven't checked if this behavior is new or already existed before the fix; in the latter case, I may remove this comment and open a separate issue.)

In any case, thanks for all the great work!

[erez-o]

If you find a consistent behavior, please create a separate issue and report it :)