Inconsistent punctuation in member function descriptions, and expressions like "i.e." or "e.g."

[gennaroprota]

Hi,

this is a screenshot of how the documentation of one of my classes appears:

As you can see, it seems that DocsForge tries to stop at the first sentence in the documentation, but sometimes it includes the final period, sometimes it doesn't.

Furthermore, there's a problem with the expression "i.e." (and, I guess, any other involving a dot, like "e.g."), as you may notice in the documentation of the first overload of set_name(). Which is weird behavior, because the letter "e" in "i.e." is included, even though it occurs after the dot (but the issue, of course, is that the dots in "i.e." should not be considered the end of the sentence).

[erez-o]

Thanks,

Currently, brief can either be written directly using @brief, or created automatically, heuristically. The heuristic is simple - find the first '. ' (there's a space following the dot) or '.\n'.

I had to restrict the period to space and \n because there were too many false alarms without it. If I remember correctly, doxygen's JAVADOC_AUTOBRIEF doesn't.

"i.e." and "e.g." are special cases that end with a dot but the sentence continues.

The problem I see is that no matter how much the heuristic is improved, there will be false alarms and misdetections.

I currently prefer to keep the heuristic simple, but I'll leave the issue open.

I think that simply replacing "i.e." with "for example" in your code comments will do the trick without hindering comment readability.

[gennaroprota]

Thanks. "e.g." could be replaced with "for example" or "for instance", but I'm a bit hesitant to replace "i.e." with "that is", because I'm afraid that could be unclear or cause ambiguities. You could tweak the heuristic to "dot followed by space or newline but not preceded by 'i.e' or 'e.g'". Otherwise, I don't know. I'll have to invent something :-)

[gennaroprota]

Oh, I forgot to say: even when no "i.e." or "e.g." is involved, you can sometimes see a terminating period, sometimes not. For instance (and not "e.g." :-)), the documentation of the first two functions ends with a period, and the one of the third function doesn't.