`inbodydescription` from Doxygen XML is not supported/rendered to Sphinx

[paulreimer]

I think that the inbodydescription style of function-descriptions-via-extracted-body-comments is not supported by breathe, although it does appear in the doxygen XML (and HTML).

In my case, I would like inbodydescription contents combined with the detaileddescription contents (and rendered similarly).

[vermeeren]

when I grep -rIn inbodydescription I notice this is already being parsed, it is however lacking output in the sphinxrenderer.py.

Currently it puts the briefdescription first, then the detaileddescription. Where should inbodydescription go? In the middle or at the end?

[Andrei1Byte]

@vermeeren I just encountered the same problem in my code. I'm using Sphinx==3.5.4, sphinx-rtd-theme==0.5.2 and breathe==4.27.0.

I the doxyfile I have defined in ALIASES some tags with table format. In the generated HTML/CHM of the doxygen the table is shown pretty nice, but is seams that Breathe/Sphinx is not processing that part.

I founded this post https://stackoverflow.com/questions/51099658/c-doxygen-breathe-tables and from what I understood the tables are not supported by Breathe.

In my case the ALIASES are used inside the function, to document the code, something like this (dummy function just for example):

void MyFunction(int test)
{   
    /// @start_tc{AA,MyFunction}
    /// @precond{Set precondition}
    SET_Precondition();
    /// @substep{Do something}
    ReadData();
    /// @substep{Check parameter @tp{param}}
    Check(param);
    /// @substep{Wait some time}
    Wait(2000);
}

From what I see in the .xml file the tag <inbodydescription> is used, which is transformed in <table> in HTML (generated by doxygen) but in index.html generated by Sphinx there is nothing related to those tables.

I also tried using list instead of table, but the same problem, the data is generated in <inbodydescription> and this is not processed further by Breathe/Sphinx.

From the stackoverflow post I understood that is possible to define the table before the function (didn't tried this yet), but I would like to also be possible to have the tags defined inside the function, like the above code.

@vermeeren do you know if there is in plan to implement something on this side ?

[Andrei1Byte]

@jakobandersen Do you know anything about this topic? :)

[jakobandersen]

As @vermeeren hinted/noted: Breathe doesn't render all the XML, it searches for bits and pieces and renders them. inbodydescription happens to be one of those nobody happened to address yet :-). The rendering of declaration descriptions is at https://github.com/michaeljones/breathe/blob/42bc2afe1446d173ccc17a2095deb9798e1fac9d/breathe/renderer/sphinxrenderer.py#L835 where you in the bottom of the function can see which items and in which order they are rendered. I don't think I have seen XML inbodydescription before, so I don't know how complicated it would be to render. But if you prepare a representative example project and an example of how the result should look (e.g., a Doxygen rendered HTML page) there is a better chance that I or someone else may dive into it ;-)

[daltonv]

This is a problem for my team as well. We document our test cases with doxygen and import those into sphinx with breathe.

So a typical test function doc would look something like this:

/**
My fun test does x, y, and z
*/
void test_my_fun_test(void)
{
    /**
      -# Step. Execute blah blah
   */
    run_func_under_test()
}

We would like the comments inside the function (the inbodydescription part to be included when rendering the function description). It feels like it would be safe to always do this, because functions authors would just not make doxygen style comments in the function if they do not want it displayed.