feature request: support for Other parameters

[mflova]

Plugins like mkdocstrings allow to split Args between Args and Other parameters. See link below:

(https://mkdocstrings.github.io/python/usage/configuration/docstrings/#show_docstring_other_parameters)

This is helpful when you want to generate documentation from docstrings while hiding some input arguments from the documentation generation. This situation happens quite often in inheritance-based patterns:

from abc import ABC, abstractmethod
from typing import Any

from typing_extensions import override


class Foo(ABC):
    @abstractmethod
    def func(self, **kwargs: Any) -> None:
        """My function
        
        Args:
            **kwargs (Any): Keyword arguments
        """

class SubFoo(Foo):
    def func(self, *, random_arg: str, **kwargs: Any) -> None:
        """My function
        
        Args:
            random_arg (str): A random arg

        Other parameters:
            **kwargs (Any): Keyword arguments
        """

In this case, the only interface requirement from Foo is a function called func that admits only keyword arguments, but can be any. If we override the class and create SubFoo, we can create our own func. In this example, I made it admit random_arg. However, I am forced to write **kwargs if I want to keep the interface where any kwargs can be sent to the function. In this case, for SubFoo, kwargs is not "technically" a useful parameter. Therefore, from the point of view of the user, I write kwargs under Other parameters and hide thsi section while generating the documentation of the function.

I am aware that you can avoid the documentation of *args and **kwargs. However, in my repository I have other functions where args and kwargs makes sense from the user point of view perspective:

def print(self, *words: str) -> None:
    """My function
    
    Args:
        *words (str): Keyword arguments
    """

Solutions I considered about this problem:

• Detect Other parameters as part of Args
• Be more flexible about *args and **kwargs: If they are found under Args:, check them. If they are not present or in Other parameters, ignore them

[mflova]

Other linters such as Ruff seem to be using the first approach in D-based rules. They merge the content of Args and Other parameters

[jsh9]

Hi @mflova ,

Is "Other parameters" an official (or at least popular) way of writing docstrings? If so, is is only for the Google style?

[mflova]

Not really. I found it in mkdocstrings and apparently, other tools such as Ruff ended up implementing this logic as well. However, I cannot trace its origin back. In official convention I did not find anything regarding this matter so I am not sure if its implementation makes sense

[jsh9]

If you have some time to implement this into the docstring parser (which pydoclint depends on), that would be a great help. And then I can modify pydoclint to incorporate this change.

I didn't write the docstring parser myself (I forked it), but I think this is where you add a detector for the section "Other parameters":
https://github.com/jsh9/docstring_parser_fork/blob/e0afb74a5a4d15f5646355f6558f6518a9569247/docstring_parser/google.py#L50-L63

And "Other parameters" is actually recognized in the numpy style in the docstring parser here: https://github.com/jsh9/docstring_parser_fork/blob/e0afb74a5a4d15f5646355f6558f6518a9569247/docstring_parser/numpydoc.py#L316

I think you can follow the logic.