[PATCH 1/3] rust: remove `params` from `module` macro docs

[PATCH 1/3] rust: remove `params` from `module` macro docs

[Aswin Unnikrishnan]

Remove nonexistent argument `params` from `module` macro example,
because the macro does not support parameter list right now.

Signed-off-by: Aswin Unnikrishnan <aswinunni01@gmail.com>
---
 rust/macros/lib.rs | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
index f489f3157383..520eae5fd792 100644
--- a/rust/macros/lib.rs
+++ b/rust/macros/lib.rs
@@ -35,18 +35,6 @@
 ///     author: "Rust for Linux Contributors",
 ///     description: "My very own kernel module!",
 ///     license: "GPL",
-///     params: {
-///        my_i32: i32 {
-///            default: 42,
-///            permissions: 0o000,
-///            description: "Example of i32",
-///        },
-///        writeable_i32: i32 {
-///            default: 42,
-///            permissions: 0o644,
-///            description: "Example of i32",
-///        },
-///    },
 /// }
 ///
 /// struct MyModule;
-- 
2.34.1

[PATCH 2/3] rust: add example for `alias` argument in `module` macro documentation

[Aswin Unnikrishnan]

Add example for `alias` argument supported by `module` macro.
`alias` accepts an array of alternate names for the module as string.

Signed-off-by: Aswin Unnikrishnan <aswinunni01@gmail.com>
---
 rust/macros/lib.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
index 520eae5fd792..aa89b41fa10e 100644
--- a/rust/macros/lib.rs
+++ b/rust/macros/lib.rs
@@ -35,6 +35,7 @@
 ///     author: "Rust for Linux Contributors",
 ///     description: "My very own kernel module!",
 ///     license: "GPL",
+///     alias: ["alternate_module_name"],
 /// }
 ///
 /// struct MyModule;
-- 
2.34.1

[PATCH 3/3] rust: fix datatype in docs for `module` macro arguments

[Aswin Unnikrishnan]

Remove the mention of byte array as datatype for `module` macro arguments
since the arguments are defined as string, and `alias` is a string array.

Signed-off-by: Aswin Unnikrishnan <aswinunni01@gmail.com>
---
 rust/macros/lib.rs | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
index aa89b41fa10e..da7cd6378288 100644
--- a/rust/macros/lib.rs
+++ b/rust/macros/lib.rs
@@ -58,11 +58,11 @@
 ///
 /// # Supported argument types
 ///   - `type`: type which implements the [`Module`] trait (required).
-///   - `name`: byte array of the name of the kernel module (required).
-///   - `author`: byte array of the author of the kernel module.
-///   - `description`: byte array of the description of the kernel module.
-///   - `license`: byte array of the license of the kernel module (required).
-///   - `alias`: byte array of alias name of the kernel module.
+///   - `name`: name of the kernel module (required).
+///   - `author`: author of the kernel module.
+///   - `description`: description of the kernel module.
+///   - `license`: license of the kernel module (required).
+///   - `alias`: array of alias names of the kernel module.
 #[proc_macro]
 pub fn module(ts: TokenStream) -> TokenStream {
     module::module(ts)
-- 
2.34.1

Re: [PATCH 1/3] rust: remove `params` from `module` macro docs

[Alice Ryhl]

On Fri, Apr 19, 2024 at 11:50 PM Aswin Unnikrishnan
<aswinunni01@gmail.com> wrote:
>
> Remove nonexistent argument `params` from `module` macro example,
> because the macro does not support parameter list right now.
>
> Signed-off-by: Aswin Unnikrishnan <aswinunni01@gmail.com>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH 2/3] rust: add example for `alias` argument in `module` macro documentation

[Alice Ryhl]

On Fri, Apr 19, 2024 at 11:50 PM Aswin Unnikrishnan
<aswinunni01@gmail.com> wrote:
>
> Add example for `alias` argument supported by `module` macro.
> `alias` accepts an array of alternate names for the module as string.
>
> Signed-off-by: Aswin Unnikrishnan <aswinunni01@gmail.com>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH 3/3] rust: fix datatype in docs for `module` macro arguments

[Alice Ryhl]

On Fri, Apr 19, 2024 at 11:50 PM Aswin Unnikrishnan
<aswinunni01@gmail.com> wrote:
>
> Remove the mention of byte array as datatype for `module` macro arguments
> since the arguments are defined as string, and `alias` is a string array.
>
> Signed-off-by: Aswin Unnikrishnan <aswinunni01@gmail.com>

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

Re: [PATCH 1/3] rust: remove `params` from `module` macro docs

[Miguel Ojeda]

On Fri, Apr 19, 2024 at 11:50 PM Aswin Unnikrishnan
<aswinunni01@gmail.com> wrote:
>
> Remove nonexistent argument `params` from `module` macro example,
> because the macro does not support parameter list right now.
>
> Signed-off-by: Aswin Unnikrishnan <aswinunni01@gmail.com>

Applied this one (1/3) to `rust-fixes` (tagged for stable too) --
thanks everyone!

[ Reworded slightly. ]

Cheers,
Miguel

Re: [PATCH 3/3] rust: fix datatype in docs for `module` macro arguments

[Miguel Ojeda]

On Fri, Apr 19, 2024 at 11:50 PM Aswin Unnikrishnan
<aswinunni01@gmail.com> wrote:
>
>  /// # Supported argument types
>  ///   - `type`: type which implements the [`Module`] trait (required).
> -///   - `name`: byte array of the name of the kernel module (required).
> -///   - `author`: byte array of the author of the kernel module.
> -///   - `description`: byte array of the description of the kernel module.
> -///   - `license`: byte array of the license of the kernel module (required).
> -///   - `alias`: byte array of alias name of the kernel module.
> +///   - `name`: name of the kernel module (required).
> +///   - `author`: author of the kernel module.
> +///   - `description`: description of the kernel module.
> +///   - `license`: license of the kernel module (required).
> +///   - `alias`: array of alias names of the kernel module.

I think the original intention here was to document mainly the "type"
of the arguments (given the title of the section), i.e. the kind of
values one can write for each key.

So it would perhaps be best to give that information, e.g. "ASCII
string literal ...". Please see the code of the macro to see which
type is required for each field (e.g. is it a literal? Does it require
ASCII? ...?).

This should probably be considered a fix, so could you please add a
`Fixes:` tag and a `Cc: stable@vger.kernel.org` one in v2 (since it
does not hurt)? See e.g. what I did for your other fix I applied
already to `rust-fixes` (but note it fixes a different commit) and
https://docs.kernel.org/process/submitting-patches.html#describe-your-changes.

Thanks!

Cheers,
Miguel