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

[erez-o]

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

[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.