netdev - [PATCH net-next] phylink: ReST-ify the phylink_pcs_neg

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Date: Mon, 26 Jun 2023 14:46:40 -0700
From: Jakub Kicinski <kuba@...nel.org>
To: davem@...emloft.net
Cc: netdev@...r.kernel.org,
	edumazet@...gle.com,
	pabeni@...hat.com,
	Jakub Kicinski <kuba@...nel.org>,
	Stephen Rothwell <sfr@...b.auug.org.au>,
	Russell King <linux@...linux.org.uk>,
	linux-doc@...r.kernel.org
Subject: [PATCH net-next] phylink: ReST-ify the phylink_pcs_neg_mode() kdoc

Stephen reports warnings when rendering phylink kdocs as HTML:

  include/linux/phylink.h:110: ERROR: Unexpected indentation.
  include/linux/phylink.h:111: WARNING: Block quote ends without a blank line; unexpected unindent.
  include/linux/phylink.h:614: WARNING: Inline literal start-string without end-string.
  include/linux/phylink.h:644: WARNING: Inline literal start-string without end-string.

Make phylink_pcs_neg_mode() use a proper list format to fix the first
two warnings.

The last two warnings, AFAICT, come from the use of shorthand like
phylink_mode_*(). Perhaps those should be special-cased at the Sphinx
level.

Reported-by: Stephen Rothwell <sfr@...b.auug.org.au>
Link: https://lore.kernel.org/all/20230626162908.2f149f98@canb.auug.org.au/
Signed-off-by: Jakub Kicinski <kuba@...nel.org>
---
CC: Russell King <linux@...linux.org.uk>
CC: linux-doc@...r.kernel.org
---
 include/linux/phylink.h | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/include/linux/phylink.h b/include/linux/phylink.h
index 516240f1e950..1817940a3418 100644
--- a/include/linux/phylink.h
+++ b/include/linux/phylink.h
@@ -105,11 +105,13 @@ static inline bool phylink_autoneg_inband(unsigned int mode)
  *
  * Determines the negotiation mode to be used by the PCS, and returns
  * one of:
- * %PHYLINK_PCS_NEG_NONE: interface mode does not support inband
- * %PHYLINK_PCS_NEG_OUTBAND: an out of band mode (e.g. reading the PHY)
+ *
+ * - %PHYLINK_PCS_NEG_NONE: interface mode does not support inband
+ * - %PHYLINK_PCS_NEG_OUTBAND: an out of band mode (e.g. reading the PHY)
  *   will be used.
- * %PHYLINK_PCS_NEG_INBAND_DISABLED: inband mode selected but autoneg disabled
- * %PHYLINK_PCS_NEG_INBAND_ENABLED: inband mode selected and autoneg enabled
+ * - %PHYLINK_PCS_NEG_INBAND_DISABLED: inband mode selected but autoneg
+ *   disabled
+ * - %PHYLINK_PCS_NEG_INBAND_ENABLED: inband mode selected and autoneg enabled
  *
  * Note: this is for cases where the PCS itself is involved in negotiation
  * (e.g. Clause 37, SGMII and similar) not Clause 73.
-- 
2.41.0