[Doxygen-users] Found some issues generating Latex from C#

[Nelis O. <noo...@co...>]

Hallo

We switched to doxygen (1.8.14) for generating our documentation (C# -> Latex). We found some issues, i'm not sure whether or not these are bugs or expected behavior (or misconfiguration on our end). I know it is quite a list, feel free to answer in parts.

I have attached example code. More detailed information is provided with the examples, a high level overview:


1)      The detailed description (subsubsection) is always shown, even though no <remarks /> tag is provided and ALWAYS_DETAILED_SEC = NO.

2)      (latex source code) properties under Property Documentation do not always start their \hbox{...} on a new line -> causes formatting issues.

3)      Abstract classes are nor marked as abstract.

4)      Constructors are marked as inline.

5)      Namespace in <see cref=""> are not shortened even though HIDE_SCOPE_NAMES = YES, i guess this is expected behavior?

6)      The Additional Inherited Members is always shown even though it is empty

7)      Internal classes are still present in the Classes list (under Namespace references), even though doxygen is configured to ignore internals.

8)      <inheritdoc/> does not work for properties and gives warnings for functions (params and return type missing) (looks like this was reported before: https://sourceforge.net/p/doxygen/discussion/130994/thread/0af65154/)

9)      Namespaces are automatically made a hyperlink in the documentation, for example: namespace Test.Exceptions -> will cause every occurrence of the word "Exceptions", in the documentation, to be a hyperlink.

Some issues i could not reproduce/provide a minimal example for:

10)   The parsing sometimes goes wrong when using \todo{}, i have had:

o   Warning: error : return type of member XXX is not documented (warning treated as error, aborting now) when using \todo{} in the remarks above the returns tag.

o   HTML generation: infinite loop/assert failure; same one as reported here: http://doxygen.10944.n7.nabble.com/ASSERT-quot-0-quot-in-docparser-cpp-5747-td7738.html. (removing \todo out of the documentation resolves this issue)

11)   I got Latex warnings about multiple defined labels.

Some additional findings/remarks:

12)   Why is \newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}} defined in the header.tex instead of the syl? (it won't work without defining the command)

13)   Why hijack \paragraph for Property Documentation entries? This may be annoying if one wants to include a custom section (text) before the documentation (if that uses \paragraph; or \subparagraph for that matter). You can use the \usepackage{titlesec} package to define custom titles if so desired.

14)   \usepackage{fixltx2e} in header.tex is no longer required or do you want it to be compatible with older tex installations? (generates: fixltx2e Warning: fixltx2e is not required with releases after 2015)

15)   If one provides a custom header.tex and it ends with a comment (e.g. %--- Begin generated content ---) the first title will be missing. The first line of the generated content will be appended, instead of starting on a new line, (and thus be commented). Therefor the header.tex may not end on a comment.

I tried to filter out all already known issues. We also encountered these (already reported) bugs:

16)   https://bugzilla.gnome.org/show_bug.cgi?id=780439 -> i would expect both classes to be in the list

17)   https://bugzilla.gnome.org/show_bug.cgi?id=638606 (fixed)

18)   https://bugzilla.gnome.org/show_bug.cgi?id=794509 (fixed)

19)   https://bugzilla.gnome.org/show_bug.cgi?id=777746 (fixed)

Thanks in advance.



==============================================

"The information contained in this e-mail message may be confidential information, and may also be privileged. If you are not the intended recipient, any use, interference with, disclosure or copying of this material is unauthorised and prohibited. If you have received this message in error, please notify us by return email and delete the original message."