linux-kernel - [RFC PATCH 0/2] Generate API documentation for 'bindings' crate

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]

Message-Id: <20230803093418.51872-1-tmgross@umich.edu>
Date:   Thu,  3 Aug 2023 05:34:16 -0400
From:   Trevor Gross <tmgross@...ch.edu>
To:     Miguel Ojeda <ojeda@...nel.org>,
        Alex Gaynor <alex.gaynor@...il.com>,
        Wedson Almeida Filho <wedsonaf@...il.com>
Cc:     Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>,
        Björn Roy Baron <bjorn3_gh@...tonmail.com>,
        Benno Lossin <benno.lossin@...ton.me>,
        rust-for-linux@...r.kernel.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, Trevor Gross <tmgross@...ch.edu>
Subject: [RFC PATCH 0/2] Generate API documentation for 'bindings' crate

The 'bindings' crate currently doesn't have API documentation available.
With this change, it will be generated as part of the output of 'make
rustdoc' (similar to the 'kernel' crate's docs,
https://rust-for-linux.github.io/docs/kernel/).

This patch is a RFC because there are a few questions:

1. Do we want to make this the default, or a separate target/
   configuration? I don't think there is much downside to always
   generating.
2. The entire '.config' file could be included in the doc output, to
   make it easy to tell what settings the documentation was generated
   with. Would this be desired? Maybe with a '--cfg
   include-dotcfg=".config"' flag so published docs would have the
   option (unsure whether it may ever have sensitive information).

Bindgen is currently invoked with '--no-doc-comments', I think this may
be because some blocks were mistakenly interpreted as doctests. Once we
upgrade our bindgen version we might be able to remove this.

Side note, 'rust/Makefile' seems to have a mix of tabs and spaces - is
this intentional?

Trevor Gross (2):
  rust: bindings: generate API documentation for the 'bindings' crate
  rust: bindings: add warning about configuration dependence

 rust/Makefile        | 14 +++++++++++---
 rust/bindings/lib.rs |  3 +++
 2 files changed, 14 insertions(+), 3 deletions(-)

-- 
2.34.1