From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 9364546B90; Wed, 16 Jul 2025 20:25:43 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 22F6C4013F; Wed, 16 Jul 2025 20:25:43 +0200 (CEST) Received: from mail-pl1-f176.google.com (mail-pl1-f176.google.com [209.85.214.176]) by mails.dpdk.org (Postfix) with ESMTP id 08291400D6 for ; Wed, 16 Jul 2025 20:25:41 +0200 (CEST) Received: by mail-pl1-f176.google.com with SMTP id d9443c01a7336-23649faf69fso1449405ad.0 for ; Wed, 16 Jul 2025 11:25:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iol.unh.edu; s=unh-iol; t=1752690341; x=1753295141; darn=dpdk.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=xnAJgVwiakVr2C5mMDhoZMzmmYJoiom3zUFlhEYBbI4=; b=avXv+pGc9+KC9gVVYLeBXNk29x/N8ByaeJM4qCpg2btWHvFzGnmmPeusCmTxZj3ZRP JPOjwn17GuTBWX6yfhVq5L+Qg/DEdeuKj6lbchS1Shqq3RISfXrrlRwVJzWT5S+wIbHB j+OwgL7GxkCQKjjx/Pw7oarvCe2v574AGZ4T8= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1752690341; x=1753295141; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=xnAJgVwiakVr2C5mMDhoZMzmmYJoiom3zUFlhEYBbI4=; b=BbMnGzfcV8r1uqiubB5JAx8E3Mew5MFSty3evGXa6+F8nvdd84+tCZJ+wQuRC9ggkd 9PSDUW2sUfEPCrwqa/pgeoO5xbBtwpVOqtm6wFTNPLnjVzYdgyqKEVu2oxvNh8MwphgY SKjbFmmXBSqK8iDWK4OgtpIAvia/16C2+5D5KHWMjLYnas4G3IOzw6g1Z/Z2pbHoXysM alyfc3VzWFFbtw+gkHsf5a5Kgmqj4TsbzoUhOF5fSEYCspSryr1XdnERzZsmzFasIiRu iexdpiIHZQOirvWmN29ImuA8w9oaaPOeeMX0nHF5hGXyaPvKxnEhBJJEWKLCT5rVgX99 F96A== X-Forwarded-Encrypted: i=1; AJvYcCXk4JaHuXngLd2SzJmBUZcdPrqRvUpAfAq6gFMXM1XJbxAk2r2Rfcpdg5vgVJRFVtS22+8=@dpdk.org X-Gm-Message-State: AOJu0YxB4Id1HLiKghK4LFRDP/3IMK+r0SazdBLgeVMY9F/8AzENe5Cg Q1nKEQ0A7ry64Mxid0nQAcMMNxsuR2G5ptFnGPgVMwCpvdBI9Gu9pDP4cZOqAicmODVBp8cwtEe tHb+7YE/3jClgkY67j2mUOGFIzw9yPJ0v2E2SgbrsMQ== X-Gm-Gg: ASbGnctWQQpKmulB5YdL2rDw7IpkZCt4A5TW26hkD3ci5g8MG7CmEDeaLQIQ5F8sTxN vz1HY3evqBgNmVpanNI5rQcqzFhlaaYEbHIJPkfLHHPyjRlwC+C2xmXol2qGYc9/N/lFWv0hsIa WRz9uYR71GDu2HwM9RCU4bBICUZdCMs8wpqdKjvVtnjlpjCJOttN5flAkpTHbJg4LqrXXVAk1Xz JThMe2fQw== X-Google-Smtp-Source: AGHT+IFV610PxcltMLxzy+/TMm6BjHpNT1hnpb93K6AX18TQE/NVoDP5xM+0Wf2DSq4UCU7SbTw1nvZPOJ185Ji7uDU= X-Received: by 2002:a17:903:1c6:b0:235:779:edfa with SMTP id d9443c01a7336-23e2572fe66mr56565595ad.32.1752690341071; Wed, 16 Jul 2025 11:25:41 -0700 (PDT) MIME-Version: 1.0 References: <20250714171346.564267-1-dmarx@iol.unh.edu> <20250716135708.49233-1-dmarx@iol.unh.edu> <20250716135708.49233-3-dmarx@iol.unh.edu> In-Reply-To: <20250716135708.49233-3-dmarx@iol.unh.edu> From: Patrick Robb Date: Wed, 16 Jul 2025 14:19:49 -0400 X-Gm-Features: Ac12FXxxIiMCwoU9ypAkfXTJ1mp1hu6gzzjcMWqOPVliNIlHwQ5p9WclRr3J3w8 Message-ID: Subject: Re: [PATCH v5 3/3] doc: revise coding guidelines section To: Dean Marx Cc: luca.vizzarro@arm.com, yoan.picchi@foss.arm.com, Honnappa.Nagarahalli@arm.com, paul.szczepanek@arm.com, dev@dpdk.org Content-Type: multipart/alternative; boundary="0000000000002e67aa063a100593" X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org --0000000000002e67aa063a100593 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Wed, Jul 16, 2025 at 9:57=E2=80=AFAM Dean Marx wrote= : > > + > +* Document ``__init__()`` separately from the class docstring. > +* If an abstract method simply implements a superclass definition withou= t > 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 enclos= e > 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 > ------------------------- > > > > --0000000000002e67aa063a100593 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Wed, Jul 16,= 2025 at 9:57=E2=80=AFAM 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 ``Attr= ibutes:``, as they are generated from the class fields.
+* Document class variables and Pydantic fields using ``#:``,
+=C2=A0 =C2=A0placed above the type-annotated line. Descriptions may be omi= tted if the meaning is clear.
+* Apply ``#:`` to ``Enum`` and ``TypedDict`` fields as well, so that autog= enerated 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 l= ine:=C2=A0https://mails.dpdk.org/archives/test-report/2025-July/894788.h= tml

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

=C2=A0
+=C2=A0 =C2=A0consistent with the `Python documentation style <https://docs.python.org/3/index.html>`_.
+* Use double backticks (````value````) for literal values.
+
+Example::
+
+=C2=A0 =C2=A0def foo(greet: bool) -> None:
+=C2=A0 =C2=A0 =C2=A0 =C2=A0"""Demonstrates single and doubl= e backticks.
+
+=C2=A0 =C2=A0 =C2=A0 =C2=A0`greet` controls whether ``Hello World`` is pri= nted.
+
+=C2=A0 =C2=A0 =C2=A0 =C2=A0Args:
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0greet: Whether to print the ``Hel= lo World`` message.
+=C2=A0 =C2=A0 =C2=A0 =C2=A0"""
+=C2=A0 =C2=A0 =C2=A0 =C2=A0if greet:
+=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0print("Hello World") +
+The maximum line length for docstrings must match that of the code.


=C2=A0How To Write a Test Suite
=C2=A0-------------------------



--0000000000002e67aa063a100593--