Closed paulreimer closed 5 years ago
Hi @paulreimer
Sorry for the late reply, I have been busy with work.
Can you provide me an example? I have not noticed this function within Doxygen, and I do not fully understand the expected output from the documentation.
Sure, here is an example (someone else's doxygen StackOverflow question) but they use in-body comments:
/*! \file best.cpp
* \brief The best
*
* I am the best
*/
/*! \fn void theBestFunction(int)
* I'm the best blah blah blah
*/
void theBestFunction(int ever)
{
doThings();
/*!
* Does some more things
*/
doMoreThings();
/*!
* Checks that the things it does are the best
*/
checkBest();
}
https://stackoverflow.com/questions/11193019/doxygen-in-body-comments
In the doxygen XML, all the in-body comments for a function are concatenated into <inbodydescription>
, a separate element from <detaileddescription>
.
In the rendered HTML from doxygen, it just adds it to the "Detailed Description" section, after the normal long description content (and that behaviour works fine for me.)
Ideally there could be a separate "Algorithm" or "Implementation" section header for these comments, but even doxygen doesn't do that.
Ah, that makes sense! Thanks for the example. I'll add the support for the <inbodydescription>
.
I am trying to avoid creating a separate section "Algorithm" / "Implementation", due to the reason that I want to make this doxybook close to the real Doxygen HTML generated.
Will make it exactly as Doxygen handles it -> append to the long description content.
Should be working now. I have pushed it to the master as v2.1.5. You can also find it on https://pypi.org/project/doxybook/#history
It won't create the section headers, the text is appended, but you can add it into the source code as markdown, see an example below:
source:
/*!
* [omitted]
* @details Lorem ipsum dolor sit amet, consectetur
* adipiscing elit, sed do eiusmod tempor incididunt
* ut labore et dolore magna aliqua.
*
* ### Implementation:
*/
inline void some_inline_member_function(Animal* animal) {
/*!
* Does some more things
*/
do_more_things();
/*!
* Checks that the things it
* does are the best
*/
check_best();
}
Doxygen original HTML:
Markdown on VuePress:
Feel free to reopen the issue if you have a problem with the implementation/or improvement.
Awesome! Thank you so much for adding that so quickly!
Good call about using markdown, I think I could also put that Implementation
header as the first in-body comment within the function (so I could disable it in doxygen
XML output later, if I wanted to)
Doxygen can extract comments within e.g. function bodies and combine them to form
<inbodydescription>
XML, similar to the<detaileddescription>
.This does appear in my Doxygen XML, (and the doxygen-generated HTML), but it does get processed by
doxybook
.