我应该记录类似功能签名的参数吗？
Should I document parameters for similar function signatures?
我有一些辅助函数，除了第一个参数外，它们采用与核心函数相同的参数。这些参数在核心函数中有完整的记录。我是否也应该将此文档复制粘贴到辅助函数中，还是只指向核心文档？
重要的是，我主要打算将我的 API 参考读作由 Sphinx 生成的 HTML，并且我使用 numpydoc 样式。我没有在 numpydoc manual.
中找到答案
编辑
这是一个 MWE：
def core(param0, param1=3, param2=8):
"""Core function with thorough documentation.
Parameters
----------
param0 : ndarray
Description.
param1 : int
Long description.
param2 : int
Long description.
Returns
-------
param_out : ndarray
Long description
"""
pass
def helper(param3, param1=3, param2=8):
"""Helper function.
"""
pass
如您所见，两个函数只有第一个参数不同。
最好、最简单的方法是使用 sphinx.ext.napoleon 扩展中的 Python Sphinx docstring sections。
只有 辅助函数 独有的参数需要明确记录，您可以 remit with a cross-reference to the function/method defining the shared parameters. The Google style guide for Python 建议相同的推理来重载从基地 class :
A method that overrides a method from a base class may have a simple docstring sending the reader to its overridden method’s docstring, such as """See base class.""". The rationale is that there is no need to repeat in many places documentation that is already present in the base method’s docstring. However, if the overriding method’s behavior is substantially different from the overridden method, or details need to be provided (e.g., documenting additional side effects), a docstring with at least those differences is required on the overriding method.
Args:
List each parameter by name. A description should follow the name, and be separated by a colon and a space.
下面的例子：
def core(param0, param1=3, param2=8):
"""Core function with thorough documentation.
Parameters
----------
param0 : ndarray
Description.
param1 : int
Long description.
param2 : int
Long description.
Returns
-------
param_out : ndarray
Long description
"""
pass
def helper(param3, param1=3, param2=8):
"""Remaining
Parameters
----------
param3 : int
Description.
Other Parameters
A short string remitting reader to :py:func:`core` function.
See Also
A short string remitting reader to :py:func:`core` function.
Note
A short string remitting reader to :py:func:`core` function.
"""
pass
会给出这样的结果：
我有一些辅助函数，除了第一个参数外，它们采用与核心函数相同的参数。这些参数在核心函数中有完整的记录。我是否也应该将此文档复制粘贴到辅助函数中，还是只指向核心文档？
重要的是，我主要打算将我的 API 参考读作由 Sphinx 生成的 HTML，并且我使用 numpydoc 样式。我没有在 numpydoc manual.
中找到答案编辑
这是一个 MWE：
def core(param0, param1=3, param2=8):
"""Core function with thorough documentation.
Parameters
----------
param0 : ndarray
Description.
param1 : int
Long description.
param2 : int
Long description.
Returns
-------
param_out : ndarray
Long description
"""
pass
def helper(param3, param1=3, param2=8):
"""Helper function.
"""
pass
如您所见，两个函数只有第一个参数不同。
最好、最简单的方法是使用 sphinx.ext.napoleon 扩展中的 Python Sphinx docstring sections。
只有 辅助函数 独有的参数需要明确记录，您可以 remit with a cross-reference to the function/method defining the shared parameters. The Google style guide for Python 建议相同的推理来重载从基地 class :
A method that overrides a method from a base class may have a simple docstring sending the reader to its overridden method’s docstring, such as """See base class.""". The rationale is that there is no need to repeat in many places documentation that is already present in the base method’s docstring. However, if the overriding method’s behavior is substantially different from the overridden method, or details need to be provided (e.g., documenting additional side effects), a docstring with at least those differences is required on the overriding method.
Args:
List each parameter by name. A description should follow the name, and be separated by a colon and a space.
下面的例子：
def core(param0, param1=3, param2=8):
"""Core function with thorough documentation.
Parameters
----------
param0 : ndarray
Description.
param1 : int
Long description.
param2 : int
Long description.
Returns
-------
param_out : ndarray
Long description
"""
pass
def helper(param3, param1=3, param2=8):
"""Remaining
Parameters
----------
param3 : int
Description.
Other Parameters
A short string remitting reader to :py:func:`core` function.
See Also
A short string remitting reader to :py:func:`core` function.
Note
A short string remitting reader to :py:func:`core` function.
"""
pass
会给出这样的结果：