Bug in generating class tag

[tsung-wei-huang]

Hi,

Our Taskflow project is using m.css for documentation. However, we found a class not correctly generated. Would you please help look at this issue?

To reproduce:

// clong https://github.com/taskflow/taskflow

~$ ./m.css/documentation/doxygen.py /path/to/taskflow/doxygen/conf.py

The class tf::Executor does not show up correctly under Classes.

Thank you.

[mosra]

Hello again!

I checked, and indeed the solution proposed at taskflow/taskflow#605 is the best you can do (except for EXTRACT_ALL, which you shouldn't need). Parsing template-heavy C++ is a complex job and given that Doxygen isn't relying on an actual compiler by default, it's kind of expected that it'd fail somewhere deep in the method definitions. (Which is also why I'm personally not running it on any *.cpp files either.)

I looked at the XML files it generates and without the proposed #ifndef there's no classtf_1_1Executor.xml generated and the executor_8hpp.xml is also completely empty. Which suggests it indeed got lost and bailed. It'd be nice if it actually printed some warning message for that, unfortunately it doesn't.

Apart from that you have basically a completely warning-free output, that's great. My only suggestion is to enable the QUIET option, then it prints only warnings in case they happen, which you can for example enforce on the CI.

[tsung-wei-huang]

Thanks @mosra , I often got the following warning after running your doxygen.py:

WARNING:root:matrix_multiplication.xml: potential issue: directory algorithm parent is not a prefix: cuda/
WARNING:root:matrix_multiplication.xml: potential issue: directory core parent is not a prefix: taskflow/
WARNING:root:matrix_multiplication.xml: potential issue: directory utility parent is not a prefix: taskflow/
WARNING:root:matrix_multiplication.xml: potential issue: directory cuda parent is not a prefix: taskflow/
WARNING:root:matrix_multiplication.xml: potential issue: directory algorithm parent is not a prefix: taskflow/
WARNING:root:classtf_1_1Runtime.xml: inline code has multiple lines, fallback to a code block
WARNING:root:classtf_1_1Runtime.xml: inline code has multiple lines, fallback to a code block
WARNING:root:DataParallelPipeline.xml: inline code has multiple lines, fallback to a code block
WARNING:root:classtf_1_1Taskflow.xml: inline code has multiple lines, fallback to a code block

Is this a big deal?

[mosra]

Ah, yes, I was actually looking at that first warning and was wondering what is it about. I made it clearer together with a fix suggestion in 083c7a8.

The second kind of warning is due to a Doxygen parsing wart. Unfortunately I don't have a nice solution for that. I opened a PR on the taskflow repo: taskflow/taskflow#625

[mosra]

Given the PR is merged, I assume that's all to be done here, thus closing.

Let me know if you need anything else.