File list remains empty in C project

[athre0z]

Hi there and thanks for maintaining this dope theme! We have been using it for quite a while now for documenting the Zydis source base.

However, there has always been the issue that, for some reason, the file list just remains empty when using the m.css generator.

Regular Doxygen HTML

m.css

Our Doxyfile and Doxyfile-mcss are part of our repo and I'd greatly appreciate if you could take a look and maybe give me a hint on why that might be happening. The generated documentation lives here.

I have already done some professional print debugging and it looks like our index file might be missing whatever XML tags matches this condition in doxygen.py, but I don't know enough about Doxygen to know why that might be the case.

[mosra]

Hi and sorry for replying two months late -- was busy on another project.

What you need to do is providing documentation also for the include, include/Zydis etc, directories, as explained in the docs (yeah, it's buried there a bit). For example:

/** @dir include
 * @brief Top-level include dir
 */
/** @dir include/Zydis
 * @brief Zydis include dir
 */

The script by default ignores files and directories that aren't annotated in any way. With this change, the file list appears correctly:

Opened https://github.com/zyantific/zydis/pull/142 with minimal changes needed to achieve this, feel free to take anything from there :)

[thomthom]

Question: What would a reasonable useful documentation comment for a directory be? I'm updating documentation for our own old docs, and we are currently using EXTRACT_ALL. I'm trying to avoid using that so our docs work better with Doxygen and m.css. But documenting files and folders are unfamiliar to me. Not sure what to say for a doc comment for a folder. Similary with a file's doc comment. We have a type per file. What is a useful comment for a file that doesn't simply parrot what the type comment is?

[mosra]

A bunch of examples:

• https://doc.magnum.graphics/magnum/files.html
• https://doc.magnum.graphics/corrade/files.html

To sum it up: for each directory I'm saying which project it is part of (magnum, in particular, is scattered among multiple repos, so some dirs might need an installation of a separate project); for files it's just a short overview what's in there ("Here's all forward declarations for this library", "Class this and that", "Intersection algorithms"). Mostly it's just a list of API names, tho.

Alternatively, some projects that have very few headers (or where everything is meant to be accessed through a single top-level heade), disable the Files view completely (using the M_NAVBAR_LINKS options). Among them is for example https://naios.github.io/continuable/ or https://marzer.github.io/tomlplusplus/.