Ability to add comments/explaination

[LabRicecat]

Is your feature request related to a problem? Please describe.

It'd be neat if you'd be able to add additional information/comments/explanations for components, such as functions, classes or whole files. So the documentation is not simply a strict list of these components, but really something you can look up when you want to know how something works or what it does.

Describe the solution you'd like

For a "quick" fix, the config option to read information from a json/toml file or similar, where the key is a symbol and the value a comment. These comment would then be placed in a "comment" section or likewise on the page it's referring to. Maybe enable HTML or markdown for these texts?

[marzer]

I'm not sure I understand. How is this different to using Doxygen's existing @brief, @details, @attention, @warning, @remark, @note, and friends?

[marzer]

Take this page, for example:

https://osgenic.github.io/stim/structstim_1_1mesh__description.html

It has all the things you're asking for, and was generated just using the built-in commands.

[LabRicecat]

Yeah, but these have to be included into the source file if I recall them correctly. I was thinking about feeding them in externally.

[marzer]

Oh, I see. I'm sorry but I won't add anything like that to poxy, largely because pegging anything to a specific symbol using Doxygen is actually Very Hard - they change their internal symbol naming logic annoyingly often so it'd be very brittle. It's also a bit outside the goals of the project, that is to be still compatible with Doxygen's in-source documentation paradigm.

If you really want it there is already a mechanism to do something approximating this built-in to Doxygen itself: tag files. Poxy exposes these as the tagfiles option.

[mosra]

There is a solution -- Doxygen has @fn <name>, @class <name>, @namespace <name>, @file <name>, @dir <name> commands as well, which allow you to document the symbols from an external file without having to "pollute" the source files. So it's then just about including that external file alongside the sources.

You're still partially at whims of how it manages to connect these to the actual C++ things, especially with heavy templates or complex function signatures, but for many things it should work. I personally use it to document namespace and directory contents, since for those there's often no "main header" where the docs should go.

[marzer]

Oh, yeah, that pattern didn't even occur to me at all. I don't think I've used that functionality, come to think of it! That is much better than using tag files, lol.