Question: copydoc-like functionality within a page

[SRGDamia1]

Is there a good way to use copydoc-like functions to copy function documentation (parameters, etc) onto a page or into a section? I would like to make pages that highlight the documentation for only 1 or two key functions from the class. These pages would be in addition to rather than in place of the full class documentation. As is, I'm getting unexpected @tparam / @param / @return / @retval / @exception found inside a @section when I try to copy function documentation.

I really appreciate this library. It made it so much easier to get much nicer looking documentation than I was able to get with Doxygen alone.

[mosra]

Hi, thanks for the appreciation :)

Hmmm. This was just a warning, though, right? Did it produce the expected output after?

The warning was put there because usually such thing was an error, but your use case looks completely valid. I'd need to think whether to add some option to silence this warning or just drop this warning altogether.

EDIT: #85 is a related issue with additional info. The question is whether such info should be discarded (current state), or copied (which may result in severe layout issues as the style isn't ready for the function detail blocks being nested).

[SRGDamia1]

The function detail blocks on the class pages are so pretty I was hoping there was a way to copy all the html and css classes into the middle of a page/section.

I think what I wanted would be impossible without either patching doxgen or doing an almost complete re-write of the xml processing (or maybe both). I didn't understand that your scripts were going mostly file-by-file and not keeping everything in memory the way I'm guessing doxygen does. I tried modifying the python to get the function parameters, but the copying that doxygen does for functions doesn't copy enough off the structure into the xml to make it work. (That is, it copies the parameter list, but none of the other parameter details like types and defaults.) And accepting the missing information, the xmltree find for function parameters eats out the parameter lists from the detailed descriptions (where section text is) so the text wouldn't go back into the same spot.

I was able to get some of what I wanted by doing an in-between process of the xml to convert the parameter list in the xml to a table and then using the parameter list formatting for that table - but that still left off the some of the prettier dimming of the default parameters and other spans as in the h3 function blocks.

What I think will work for me to get the look I want (and might logically make more sense) is to convert my pages into groups and then including the functions I wanted to copy the docs for as members of the group. Where that doesn't make sense, I might end up (manually or programatically) post-processing the html to get what I want.

[mosra]

Oh, I see, so you wanted to copy the whole thing :) Hmm.

Yes, Doxygen's @copywhatever alone would be insufficient for this. Right now the actual styling is divided partly between a rigidly-produced HTML markup for prose (brief/detailed description, parameter description and such) and a Jinja template that takes all properties a function has and forms that into this nice block.

So, in order to do this, there would need to be a way to take this Jinja template and a particular function, process those and then embed them in the middle of a HTML markup. An ugly way could be a post-processing step:

1. put some sort of placeholder (let's say {{ function-detail-g56456adab9055 }}) in the text
2. using some XML parsing library extract a <section id="g56456adab9055"> (every function on a page has some unique hash, but don't assume any sanity from Doxygen, there's no sane documented hashing unfortunately) out of the produced HTML
3. replace that placeholder with that extracted section

Yeah, it's ugly. But -- and that's what I really invested time into -- the generated HTML is designed to be really clean to allow such postprocessing.

What you're asking for goes more in the direction of how Sphinx works (where you are required to build your docs out of classes, functions etc. explicitly listed on a page instead of the tool autogenerating the reference for you), but this tool is not there yet, it's just fixing the pages Doxygen produced. I was thinking about this direction when I made the Python doc theme and it might eventually get done, but based on how busy I am all the time I can't promise anything :sweat_smile: In particular, while this could be rather easy to do for the Python backend (which is written from scratch), it might be easier to just rewrite the C++ backend from scratch without Doxygen than trying to bend it to support this.

[SRGDamia1]

I did almost exactly what you suggested to get things looking how I wanted. I used an @ref inside of my placeholder to get doxygen to put the function id hash there for me so I didn't have to look it up and fix it whenever it changed.

Thank you so much!

If you're interested, the final results are here: https://envirodiy.github.io/ModularSensors/index.html.