Reading Docstrings
Python Google/NumPy/Sphinx styles, JSDoc tags — understanding documented function contracts
Docstring formats at a glance
- Google (Python): Args: / Returns: / Raises: / Example: sections with indented content
- NumPy (Python): Parameters / Returns / Raises sections with dashes underlines
- Sphinx/RST (Python): :param name: / :returns: / :raises ExType: inline directives
- JSDoc (JS/TS): @param / @returns / @throws / @deprecated / @example tags
- Javadoc (Java): @param / @return / @throws / @see tags
Question 0 of 5
Read this Python docstring and answer: what does the function return when no user is found?def get_user(user_id: int) -> Optional[User]:
"""Retrieve a user by their ID.
Args:
user_id: The unique identifier of the user.
Returns:
The User object if found, or None if no user exists
with the given ID.
"""
- Args: — describes each parameter
- Returns: — describes the return value and edge cases
- Raises: — lists exceptions that can be thrown
- Example: — shows usage
What does the @throws tag mean in this JSDoc?/**
* Parses a JSON configuration file.
* @param {string} filePath - Path to the config file
* @returns {Config} The parsed configuration object
* @throws {SyntaxError} If the file contains invalid JSON
* @throws {Error} If the file cannot be read
*/
@throws (also written as @exception in some styles) documents potential errors: @throws {SyntaxError}— only when the JSON is malformed@throws {Error}— only when the file cannot be read (e.g., permission denied)
@param (parameter), @returns (return value), @throws (exceptions), @example (usage), @deprecated (do not use), @since (version added).A NumPy-style docstring has this section:Parameters
----------
n_components : int, default=2
Number of principal components to compute.
whiten : bool, default=False
When True, the components are whitened.
Which parameter is optional and what is its default value?
- The format is
name : type, default=value - If a default is shown, the parameter is optional
- If no default is shown, the parameter is typically required
Parameters\n----------) are the signature of NumPy style.What does the @deprecated JSDoc tag tell you?
@deprecated signals: - This function still works, but is considered outdated
- A replacement is usually suggested:
@deprecated Use newFunction() instead. - IDEs (VS Code, IntelliJ) show a ~~strikethrough~~ on deprecated calls to warn developers
@deprecated is critical when working with third-party libraries — using deprecated APIs can break your code when the library is updated. Always check the suggested replacement.In a reStructuredText (Sphinx) docstring, what does this section document?:raises ValueError: If the input list is empty.
:raises TypeError: If the input is not a list.
:raises ExceptionType: directive documents when exceptions are thrown. Comparison of docstring formats for exceptions: - Google style:
Raises: ValueError: If the list is empty. - NumPy style:
Raises\n------\nValueError\n If the list is empty. - Sphinx/RST style:
:raises ValueError: If the list is empty.