Add support for :private-members: option

Previously all constructs for a C file were auto documented unless the
:members: option was used to limit to specific named items.
Now by default the autocmodule directive will only autodocument members
which are either non static functions, non static variables.  Unless the
module is a header file, .h, then all constructs will still be
documented.  The :private-members: option must be used to automatically
auto document all of the c constructs in a module. The
:no-private-members: option also becomes available to allow defaulting
to :private-members: and selectivly limiting on a per module basis.

Author: speedyleion

CHANGELOG.rst

@@ -9,14 +9,21 @@ This project adheres to `Semantic Versioning <https://semver.org/>`_.
 `v0.3.0-dev`_ (unreleased)
 ==========================
 
-`v0.2.0`_ (2020-04-1)
+`v0.2.0`_ (2020-04-04)
 ==========================
 
 Added
 -----
 
 * Viewcode functionality which allows for listing the source C files and
   providing links between the documentation and the C source listings.
+* :private-members: and :no-private-members: option for the autocmodule
+  directive. This option set allows for controlling the documentation of
+  constructs based on what is visible outside of the module. For header
+  files this means everything will still be documented. For standard source
+  files only non static functions and non static variables will be auto
+  documented if the :private-members: is not specified, or the
+  :no-private-members: is specified.
 
 Fixes
 -----

docs/directives.rst

@@ -36,9 +36,9 @@ instance from being added to the index provide this option.
         This option has 4 states:
 
         - Omitted will result in the ``members`` entry of
-          `autodoc_default_options <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options>`_
-          being used.  If ``members`` is omitted from
-          `autodoc_default_options <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options>`_ then no members will be automatically documented.
+          `autodoc_default_options`_ being used. If ``members`` is omitted
+          from `autodoc_default_options`_ then no members will be
+          automatically documented.
         - Specified as ``:no-members:``, no members will be automatically
           documented.
         - Specified with no arguments, ``:members:``, then all supported C
@@ -47,6 +47,25 @@ instance from being added to the index provide this option.
           ``:members: function_a, struct_b``, only the file members specified will
           be recursively documented.
 
+    .. rst:directive:option:: private-members
+
+        Specify if private members are to be documented. Since C doesn't
+        actually have a true idea of public and private, the following rules
+        are used to determine these characteristics.
+
+        Members are public if:
+
+            - They are in a header file, ends in `.h`. By nature header files are meant to
+              be included in other files, thus anything declared there is
+              deamed public.
+            - They can be visible outside of the compilation unit. These are
+              things the linker can get access to. Mainly this means functions
+              and variables that are not static.
+
+        Just as for the standard `autodoc`_ options, one can use the negated
+        form of ``:no-private-members:`` to selectivly turn off this option
+        on a per module basis.
+
 .. rst:directive:: .. autocfunction:: filename::function
 
     Document the function ``function`` from file ``filename``.
@@ -78,10 +97,9 @@ instance from being added to the index provide this option.
         This option has 4 states:
 
         - Omitted will result in the ``members`` entry of
-          `autodoc_default_options <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options>`_
-          being used.  If ``members`` is omitted from
-          `autodoc_default_options <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options>`_
-          then no members will be automatically documented.
+          `autodoc_default_options`_ being used. If ``members`` is omitted
+          from `autodoc_default_options`_ then no members will be
+          automatically documented.
         - Specified as ``:no-members:``, no members will be automatically
           documented.
         - Specified with no arguments, ``:members:``, then all fields (if struct
@@ -101,12 +119,13 @@ instance from being added to the index provide this option.
     constant (if an enum).
 
     .. note:: This is one of the overloaded uses of the term **member**. This
-        name was used to keep consistent with the
-        `member <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-c:member>`_
-        wording of the `C domain`_.
+        name was used to keep consistent with the `member`_ wording of the
+        `C domain`_.
 
 .. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+.. _member: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-c:member
 .. _domain: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html
 .. _C domain: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain
 .. _Sphinx: https://www.sphinx-doc.org/en/master/index.html
 .. _Doxygen: http://www.doxygen.nl/
+.. _autodoc_default_options: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options

src/sphinx_c_autodoc/__init__.py

@@ -78,7 +78,11 @@ class CObjectDocumenter(Documenter):
     # objects
     priority = 11
 
-    option_spec = {"members": members_option, "noindex": bool_option}
+    option_spec = {
+        "members": members_option,
+        "noindex": bool_option,
+        "private-members": bool_option,
+    }
 
     @classmethod
     def can_document_member(
@@ -276,22 +280,30 @@ def filter_members(
     ) -> List[Tuple[str, Any, bool]]:
         """Filter the given member list.
 
+        :meth:`filter_members` is called *after* :meth:`get_object_members`,
+        this means if `want_all` is False then only private members which
+        were explicitly requested will be in this list. Only when `want_all`
+        is True do we need to actually condition on private member.
+
         Members are skipped if
 
         - they are private (except if given explicitly or the private-members
           option is set)
-        - they are special methods (except if given explicitly or the
-          special-members option is set)
         - they are undocumented (except if the undoc-members option is set)
+          TODO not implemented yet.
 
+        TODO not implemented yet.
         The user can override the skipping decision by connecting to the
         ``autodoc-skip-member`` event.
         """
         ret = []
         isattr = False
         for (membername, member) in members:
-            ret.append((membername, member, isattr))
-
+            if not want_all:
+                ret.append((membername, member, isattr))
+            else:
+                if member.is_public() or self.options.private_members:
+                    ret.append((membername, member, isattr))
         return ret
 
     def format_name(self) -> str:

src/sphinx_c_autodoc/loader.py

@@ -14,7 +14,7 @@
 from bs4 import BeautifulSoup
 from bs4.element import Tag
 from clang import cindex
-from clang.cindex import Cursor, Token
+from clang.cindex import Cursor, Token, StorageClass
 
 from sphinx_c_autodoc.clang.patches import patch_clang
 
@@ -242,6 +242,29 @@ def get_paragraph(tag: Optional[Tag]) -> str:
         paragraph += "\n"
         return paragraph
 
+    def is_public(self) -> bool:
+        """
+        Determines if this item is public.
+
+        C doesn't actually have public/private namespace so we're going to
+        make up some rules.
+
+        Constructs are public if:
+
+            - They are in a header file. By nature header files are meant to
+              be included in other files, thus they are deamed public.
+
+            - They can be visible outside of the compilation unit. These are
+              things the linker can get access to. Mainly this means functions
+              and variables that are not static.
+        """
+        # Here we'll do the most common logic, and let specific constructs that
+        # can be public do special logic.
+        if self.node.location.file.name.endswith(".h"):
+            return True
+
+        return False
+
 
 class DocumentedFile(DocumentedObject):
     """
@@ -354,6 +377,13 @@ def get_parsed_declaration(self) -> str:
         type_ = self.node.type.spelling
         return f"{type_} {self.name}"
 
+    def is_public(self) -> bool:
+        """
+        Members are always public, because it's their parents that determine
+        public versus private.
+        """
+        return True
+
 
 class DocumentedFunction(DocumentedObject):
     """
@@ -447,6 +477,15 @@ def get_parsed_declaration(self) -> str:
 
         return "{} {}({})".format(return_type, func.spelling, ", ".join(args))
 
+    def is_public(self) -> bool:
+        """
+        Functions are public as long as they are not static.
+        """
+        if self.node.storage_class == StorageClass.STATIC:
+            return False
+
+        return True
+
 
 class DocumentedType(DocumentedObject):
     """
@@ -517,7 +556,7 @@ class DocumentedUnion(DocumentedStructure):
 
 class DocumentedEnum(DocumentedStructure):
     """
-    Class for unions. Same as structures with a different :attr:`type`.
+    Class for Enumerations. Same as structures with a different :attr:`type`.
     """
 
     type_ = "enum"
@@ -547,6 +586,15 @@ def format_name(self) -> str:
         name, _, _ = decl.partition("=")
         return name
 
+    def is_public(self) -> bool:
+        """
+        Variables are public as long as they are not static.
+        """
+        if self.node.storage_class == StorageClass.STATIC:
+            return False
+
+        return True
+
 
 CURSORKIND_TO_OBJECT_CLASS = {
     cindex.CursorKind.TRANSLATION_UNIT: DocumentedFile,

tests/assets/c_source_2/file_with_private_members.c

@@ -0,0 +1,49 @@
+/**
+ * Defines in C files are inherently private.
+ */
+#define PRIVATE_MACRO 3
+
+/**
+ * Function macros in C files should also be private
+ */
+#define PRIVATE_FUNCTION_MACRO(_a, _b)\
+    (_a) + (_b)
+
+/**
+ * Types, in c files are inherently private.
+ */
+typedef int foo;
+
+/**
+ * static variables are inherently private
+ */
+static int my_var;
+
+/**
+ * Non static variables are not private
+ */
+float a_public_var;
+
+/**
+ * Enumerations in c files are inherently private
+ */
+enum private_enum {
+    ENUM_1
+};
+
+/**
+ * structures in c files are inherently private
+ */
+struct private_struct {
+    int a;
+};
+
+/**
+ * Non static functions are not private
+ */
+void function1(int a);
+
+/**
+ * static functions, in c files are inherently private.
+ */
+static void function2(int a);

tests/assets/c_source_2/header_with_types.h

@@ -0,0 +1,4 @@
+/**
+ * This should always be visible, even if ``no-private-members`` is in use.
+ */
+typedef float header_type;

tests/assets/conf.py

@@ -192,6 +192,9 @@
 
 
 # -- Extension configuration -------------------------------------------------
+autodoc_default_options = {
+    "private-members": True,
+}
 
 primary_domain = "c"
 c_autodoc_roots = ["c_source", "c_source_2", "c_source_2/nested"]