linux-kernel - Re: [PATCH] rust: Use consistent "# Examples" heading style in rustdoc

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-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CANiq72mhyBOjzmvmUDfgFBoRqO_aaS-CL-ct3vmJ56HoJAsV4A@mail.gmail.com>
Date: Tue, 10 Jun 2025 10:34:47 +0200
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Viresh Kumar <viresh.kumar@...aro.org>
Cc: Andreas Hindborg <a.hindborg@...nel.org>, Boqun Feng <boqun.feng@...il.com>, 
	Michael Turquette <mturquette@...libre.com>, Stephen Boyd <sboyd@...nel.org>, 
	Miguel Ojeda <ojeda@...nel.org>, Alex Gaynor <alex.gaynor@...il.com>, Gary Guo <gary@...yguo.net>, 
	Björn Roy Baron <bjorn3_gh@...tonmail.com>, 
	Benno Lossin <lossin@...nel.org>, Alice Ryhl <aliceryhl@...gle.com>, 
	Trevor Gross <tmgross@...ch.edu>, Danilo Krummrich <dakr@...nel.org>, Breno Leitao <leitao@...ian.org>, 
	"Rafael J. Wysocki" <rafael@...nel.org>, Yury Norov <yury.norov@...il.com>, 
	Greg Kroah-Hartman <gregkh@...uxfoundation.org>, Luis Chamberlain <mcgrof@...nel.org>, 
	Russ Weight <russ.weight@...ux.dev>, Nishanth Menon <nm@...com>, Bjorn Helgaas <bhelgaas@...gle.com>, 
	Krzysztof Wilczyński <kwilczynski@...nel.org>, 
	Vincent Guittot <vincent.guittot@...aro.org>, linux-block@...r.kernel.org, 
	rust-for-linux@...r.kernel.org, linux-kernel@...r.kernel.org, 
	linux-clk@...r.kernel.org, linux-pm@...r.kernel.org, 
	linux-pci@...r.kernel.org
Subject: Re: [PATCH] rust: Use consistent "# Examples" heading style in rustdoc

On Tue, Jun 10, 2025 at 6:38 AM Viresh Kumar <viresh.kumar@...aro.org> wrote:
>
> Some modules previously used `## Examples` or `# Example`, which deviates
> from the preferred `# Examples` style.

Note that `##` is not necessarily wrong, it depends on the intended
header level. Top-level headers use `#`, second level is `##`, and so
on.

(In particular, it shouldn't be used as a hack to get smaller font
size in the rendered form).

So, for instance, in the `workqueue.rs` one in this patch, the example
is likely intended to be a subsection of the "safe API" section, not
an example of everything, so I don't think that one should change.

Thanks!

Cheers,
Miguel