Re: [PATCH v5 3/3] doc: revise coding guidelines section

[Patrick Robb <probb@iol.unh.edu>]

[-- Attachment #1: Type: text/plain, Size: 2030 bytes --]

On Wed, Jul 16, 2025 at 9:57 AM Dean Marx <dmarx@iol.unh.edu> wrote:

>
> +
> +* Document ``__init__()`` separately from the class docstring.
> +* If an abstract method simply implements a superclass definition without
> changes, refer to that superclass in the docstring.
> +* Document instance variables in the class docstring under an
> ``Attributes:`` section.
> +* For ``@dataclass`` classes, document instance-level attributes in
> ``Attributes:``, as they are generated from the class fields.
> +* Document class variables and Pydantic fields using ``#:``,
> +   placed above the type-annotated line. Descriptions may be omitted if
> the meaning is clear.
> +* Apply ``#:`` to ``Enum`` and ``TypedDict`` fields as well, so that
> autogenerated documentation includes their values.
> +* When referring to a parameter in a docstring, omit articles and enclose
> the parameter in single backticks (e.g., `` `param` ``),
>

There is actually a docs build failure on GHA from this line:
https://mails.dpdk.org/archives/test-report/2025-July/894788.html

One option would be to escape the backticks like \`. But, it's even better
to just drop the inline single and double backtick examples given that you
have an example block below which shows both. So, keep the bulleted
descriptions, but remove the examples in parenthesis.



> +   consistent with the `Python documentation style <
> https://docs.python.org/3/index.html>`_.
> +* Use double backticks (````value````) for literal values.
> +
> +Example::
> +
> +   def foo(greet: bool) -> None:
> +       """Demonstrates single and double backticks.
> +
> +       `greet` controls whether ``Hello World`` is printed.
> +
> +       Args:
> +           greet: Whether to print the ``Hello World`` message.
> +       """
> +       if greet:
> +           print("Hello World")
> +
> +The maximum line length for docstrings must match that of the code.
>
>
>  How To Write a Test Suite
>  -------------------------
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 2852 bytes --]