Fix comments in function declarations showing up in documentation.

When comments were placed inbetween parameter types and the parameter
names, and the type was unknown to clang, the fallback parsing would
take the declaration character for character (consolidating whitespace).
This resulted in comments being pulled in to the documentation verbatim.
Now comments will explicitly be skipped over when the fall back parsing
for function declarations happens.

Author: speedyleion

CHANGELOG.rst

@@ -9,6 +9,17 @@ This project adheres to `Semantic Versioning <https://semver.org/>`_.
 `v0.3.0-dev`_ (unreleased)
 ==========================
 
+Fixes
+-----
+
+* Fix comments in function declarations showing up in documentation. When
+  comments were placed inbetween parameter types and the parameter names, and
+  the type was unknown to clang, the fallback parsing would take the
+  declaration character for character (consolidating whitespace). This
+  resulted in comments being pulled in to the documentation verbatim. Now
+  comments will explicitly be skipped over when the fall back parsing for
+  function declarations happens.
+
 `v0.2.0`_ (2020-04-04)
 ==========================
 
@@ -17,7 +28,7 @@ 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
+* `: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
@@ -28,20 +39,20 @@ Added
 Fixes
 -----
 
-*  Anonymous enumerations which were contained in a typedef were being documented twice.
-   Once as the typedef and once as anonymous. Now they are only documnted as
-   part of the typedef.
+* Anonymous enumerations which were contained in a typedef were being documented twice.
+  Once as the typedef and once as anonymous. Now they are only documnted as
+  part of the typedef.
 
 `v0.1.1`_ (2020-03-15)
 ======================
 
 Fixes
 -----
 
-*  C module is not resolved relative to the document root,
-   `#1 <https://github.com/speedyleion/sphinx-c-autodoc/issues/1>`_.
-*  C module can not be specified in a sub directory,
-   `#2 <https://github.com/speedyleion/sphinx-c-autodoc/issues/2>`_.
+* C module is not resolved relative to the document root,
+  `#1 <https://github.com/speedyleion/sphinx-c-autodoc/issues/1>`_.
+* C module can not be specified in a sub directory,
+  `#2 <https://github.com/speedyleion/sphinx-c-autodoc/issues/2>`_.
 
 `v0.1.0`_ (2020-03-07)
 ======================

src/sphinx_c_autodoc/loader.py

@@ -459,7 +459,10 @@ def get_parsed_declaration(self) -> str:
         func = self.node
         args = []
         for arg in func.get_arguments():
-            args.append(" ".join(t.spelling for t in arg.get_tokens()))
+            non_comment_tokens = (
+                t for t in arg.get_tokens() if t.kind != cindex.TokenKind.COMMENT
+            )
+            args.append(" ".join(t.spelling for t in non_comment_tokens))
 
         tu = func.tu
 

tests/assets/c_source_2/nested/functions.c

@@ -78,4 +78,15 @@ void doxy_documented_parameters_no_returns(int water, int air)
  *     first_param: A parameter to document
  *     second_param: Why not
  */
-void * custom_napoleon_section(char first_param, int second_param);
+void * custom_napoleon_section(char first_param, int second_param);
+
+/**
+ * A function with comment inside of parameter declaration.
+ *
+ * Parameters:
+ *     my_char_ptr: Pointer to my character, probably actually an array
+ *         or string like representation.
+ */
+void * function_with_comment_in_parameter(
+    const unknown_type * /* A comment in the middle of parameter line */
+        my_char_ptr );

tests/directives/test_autocfunction.py

@@ -71,6 +71,13 @@ class TestAutoCFunction:
         FUNCTION_LIKE_MACRO_x, _y
         A function like macro with 2 parameters"""
 
+    function_with_comment_in_parameter = """\
+        void * function_with_comment_in_parameterconst unknown_type *\xa0my_char_ptr
+        A function with comment inside of parameter declaration.
+        Parameters
+        my_char_ptr -- Pointer to my character, probably actually an array
+        or string like representation."""
+
     doc_data = [
         ("functions.c::single_line_function_comment", single_line_comment),
         ("functions.c::return_value_function", return_value_function),
@@ -83,6 +90,10 @@ class TestAutoCFunction:
         ),
         ("functions.c::undocumented_function", undocumented_function),
         ("macros.c::FUNCTION_LIKE_MACRO", function_like_macro),
+        (
+            "functions.c::function_with_comment_in_parameter",
+            function_with_comment_in_parameter,
+        ),
     ]
 
     @pytest.mark.parametrize("function, expected_doc", doc_data)