Feature request: Incorporate no-undoc-members from autodoc about sphinx-c-autodoc HOT 3 CLOSED

The idea being that developers should have to put no effort in beyond commenting their code to get documentation for it.

I agree, try to make it as automatic for the majority of cases, but still overridable for those that want customization.

One constraint I have found is that sphinx will emit a warning for duplicate member declarations across different files

One idea I've been trying to consider, is doing like doxygen and combining the documentation from the declaration and the definition. I think it would require an option to let the user specify if the docs go at the declaration or the definition location.

I would suggest adding a feature where prototypes declared within a header file with no documentation should either be skipped completely.

I wonder if this specific instance might be better served by bringing in the no-undoc-members from autodoc.
I think this would be a bit more robust than the no doc == private, in case someone still wants to document private, but not document undocumented members. Thinking static module variables or defines.
I need to check, but I think right now in its current form the extension will try to document header include guards.

#ifndef MY_INCLUDE_GUARD
#define MY_INCLUDE_GUARD  // <-- I think this shows up in header docs

I didn't know about the meta tags, thanks for sharing that. I agree for the current use case the meta tags might too much manual work on the documentation writers.

If you would like me to make a PR for this issue just let me know and I can do that

That's up to you if you want to do a PR. I don't think I've done a good job of documenting the tests, so it would be interesting what your take is on them and how easy or not you find them to extend.

Sorry for all the issues recently

I'm excited you you're both using the extension and taking the time to point out flaws and propose improvements. Even though C is a smaller language than some, the practices people have vary quite widely and it's good to hear how this could be improved to support others.

from sphinx-c-autodoc.

One idea I've been trying to consider, is doing like doxygen and combining the documentation from the declaration and the definition. I think it would require an option to let the user specify if the docs go at the declaration or the definition location.

I think adding something like this would be incredibly useful, especially if also integrated with the viewsource extension, which would allow the developer to define the documentation in a header file, have it show up in the source (or header) and have it link to the source code.

I need to check, but I think right now in its current form the extension will try to document header include guards.

I can confirm that it will document header guards

I'm excited you're both using the extension and taking the time to point out flaws and propose improvements. Even though C is a smaller language than some, the practices people have vary quite widely and it's good to hear how this could be improved to support others.

I'm glad to hear you are excited. I'm glad that you are interested in making this a really useful tool and are willing to apply my finding from my particular use cases.

from sphinx-c-autodoc.

I redefined the issue to better address the requested feature based off of this comment

I wonder if this specific instance might be better served by bringing in the no-undoc-members from autodoc.
I think this would be a bit more robust than the no doc == private, in case someone still wants to document private, but not document undocumented members. Thinking static module variables or defines.

After working more with this extension this is much more along the lines of what I am looking for than my original request

from sphinx-c-autodoc.