Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Trevor Gross <tmgross@umich.edu>
To:     Miguel Ojeda <ojeda@kernel.org>,
        Alex Gaynor <alex.gaynor@gmail.com>,
        Wedson Almeida Filho <wedsonaf@gmail.com>
Cc:     Boqun Feng <boqun.feng@gmail.com>, Gary Guo <gary@garyguo.net>,
        =?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?= <bjorn3_gh@protonmail.com>,
        Benno Lossin <benno.lossin@proton.me>,
        rust-for-linux@vger.kernel.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org, Trevor Gross <tmgross@umich.edu>
Subject: [RFC PATCH 0/2] Generate API documentation for 'bindings' crate
Date:   Thu,  3 Aug 2023 05:34:16 -0400
Message-Id: <20230803093418.51872-1-tmgross@umich.edu>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

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