C++ documentation with no undocumented members?

[wsnyder]

I'm a new breathe user, so perhaps this is documented, but the closest I could find was #183.

I'm trying to suppress undocumented defines (etc) from Doxygen into Breathe (into Sphinx into HTML), but they are landing in my HTML regardless of my attempts.

My .rst file for now is just this:

 .. doxygenindex::

Note I am/need to run doxygen standalone, not with your auto call.

Being a bit familiar with standalone Doxygen, I tried configuring Doxygen with:

EXTRACT_ALL            = NO
EXTRACT_LOCAL_CLASSES  = NO
EXTRACT_PRIVATE        = NO
EXTRACT_STATIC         = YES
HIDE_FRIEND_COMPOUNDS  = YES
HIDE_IN_BODY_DOCS      = YES
HIDE_UNDOC_CLASSES     = YES
HIDE_UNDOC_MEMBERS     = YES
INTERNAL_DOCS          = NO

but figured out that Doxygen ignores HIDE_UNDOC_MEMBERS for XML output (Sigh).

Looking at the breathe sources there seems to be XML node filtering that can be applied.

I then guessed from a comment in #183 that the filtering doesn't get applied to the doxygenindex output?

So, when I change to use

.. doxygenindex::

.. doxygenclass:: MyClassName
   :members:

.. doxygenfile:: myheader.h

I see that doxygenclass properly shows only documented members, but doxygenfile shows everything. I probably would be willing to use doxygenfile but it has the same issues.

1. Is there a way to get "only documented" across all contents in one tag (e.g. doxygenindex)
2. Is there a way to get "only documented" with doxygenfile?
3. Alternatively, is there a way to apply filtering through some hack?
4. Or is there an alternative use model I'm missing that is common that gets around this (and doesn't require listing every class etc)?

Thanks

[vermeeren]

@wsnyder I don't think there is an easy way to do what you want, indeed #183 is relevant and at the time in #183 (comment) I considered this to be potentially a Doxygen bug, as settings should (and usually do) also effect XML output. If it is not yet reported on the Doxygen side as a bug, perhaps we would give that a shot and see what their reply is.

Generally speaking when using Breathe I personally suggest writing documentation manually, which involves manual sectioning and page layout determination using Breathe to insert the definitions from Doxygen here as there. This is more work compared to a plain API listing but significantly higher quality and more helpful, especially for newcomers to an API as it has a lot more structure and additional paragraphs explaining concepts.

However, if you wish to have a mostly fully automated Doxygen-style bare API listing you can likely use, from #38 (comment)

Probably either breathe-apidoc or https://github.com/svenevs/exhale do what is desired. If not, #321 will surely be the answer.

Perhaps one of these two utilities will do what you want. breathe-apidoc does work but is not really documented in the main docs, just the --help output of the script. Also relevant is #293 and #357.

Thoughts?

[wsnyder]

I started down the path of having a script filter the XML which was going OK, but I ended up not deploying any breathe documentation for now. So think I'm all set for now.