Your data-science team uses Sphinx with the napoleon extension to build API documentation directly from Numpy/Google-style docstrings. A teammate submits the following code:
The docstring violates established conventions and will not render correctly in the generated docs. Which revised docstring best follows PEP 257 and common Numpy/Google guidelines so that automated tools can capture the function's contract unambiguously?
"""COMPUTE_AUC(Y_TRUE, Y_PROB)
Returns
-------
float
Area under curve.
"""
"""Returns AUC. Implementation details:
- Calls roc_auc_score inside a Cython loop
- TODO: Optimize with SIMD
"""
"""Compute the area under the ROC curve (AUC).
Parameters
----------
y_true : array-like of shape (n_samples,)
Ground-truth binary labels (0 or 1).
y_prob : array-like of shape (n_samples,)
Predicted probabilities for the positive class.
Returns
-------
float
AUC score in the range .
Raises
------
ValueError
If y_true and y_prob have different lengths.
"""
PEP 257 states that a multi-line docstring begins with a one-sentence summary line, followed by a blank line and a more detailed description of arguments, return values, side-effects/exceptions, and any usage constraints. It explicitly discourages repeating the function signature in the summary. The Google Python Style Guide (and Numpydoc) further standardizes section headers such as Parameters, Returns, and Raises so that tools like Sphinx-napoleon can parse them.
The correct option supplies:
An imperative one-line summary ("Compute the area under the ROC curve (AUC).")
A blank line after the summary
Structured Parameters, Returns, and Raises sections that include type/shape information
Triple double quotes and no duplicated signature text
The distractors each break at least one key rule: repeating the signature, omitting the blank line, failing to describe parameters/returns, capitalizing parameter names in running text, or focusing on low-level implementation details that PEP 257 says belong in inline comments, not docstrings.
Ask Bash
Bash is our AI bot, trained to help you pass your exam. AI Generated Content may display inaccurate information, always double-check anything important.
What is PEP 257, and why is it important?
Open an interactive chat with Bash
What role does the Sphinx-napoleon extension play in API documentation?
Open an interactive chat with Bash
How do Numpy and Google-style docstrings differ in format?