Skip to contentSkip to conversation

rust: remove `params` from `module` macro docs

PATCH Applied Aswin Unnikrishnan 3 participants 8 messages Apr 19, 2024 – Apr 23, 2024 Rust

lore
Share & tools
lore
#0 lore raw

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

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

---
 rust/macros/lib.rs | 12 ------------
 1 file changed, 12 deletions(-)
rust/macros/lib.rs +0 -12
index f489f3157383..520eae5fd792 100644
@@ -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;
Signature · 1 line
2.34.1
#1 lore raw

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

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

---
 rust/macros/lib.rs | 1 +
 1 file changed, 1 insertion(+)
rust/macros/lib.rs +1 -0
index 520eae5fd792..aa89b41fa10e 100644
@@ -35,6 +35,7 @@
 ///     author: "Rust for Linux Contributors",
 ///     description: "My very own kernel module!",
 ///     license: "GPL",
+///     alias: ["alternate_module_name"],
 /// }
 ///
 /// struct MyModule;
Signature · 1 line
2.34.1
#3 lore raw

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

In reply to 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.

---
 rust/macros/lib.rs | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
rust/macros/lib.rs +5 -5
index aa89b41fa10e..da7cd6378288 100644
@@ -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)
Signature · 1 line
2.34.1
#5 lore raw

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

In reply to Aswin Unnikrishnan

rust/macros/lib.rs line 65

Quoted 13 lines · Aswin Unnikrishnan

/// # Supported argument types
/// - type: type which implements the [Module] trait (required).

rust/macros/lib.rs +5 -5
-///   - `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: [email protected] 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