[PATCH] samples: rust_misc_device: fix markup in top-level docs

[PATCH] samples: rust_misc_device: fix markup in top-level docs

[Alice Ryhl]

The meaning of /// is to document the thing that comes after it, so
currently the example is documentation for the `use core::pin::Pin;`
statement. To write top-level docs (and have them rendered as such in
the html by rustdoc), use //! instead.

This does not change the contents of the docs at all. The only change is
changing /// to //!.

Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
 samples/rust/rust_misc_device.rs | 181 ++++++++++++++++++++-------------------
 1 file changed, 91 insertions(+), 90 deletions(-)

diff --git a/samples/rust/rust_misc_device.rs b/samples/rust/rust_misc_device.rs
index 40ad7266c2252e5c0b4e91e501ef9ada2eda3b16..17ae59979dd05d3e240966e598e5ce0cbf10ef18 100644
--- a/samples/rust/rust_misc_device.rs
+++ b/samples/rust/rust_misc_device.rs
@@ -3,97 +3,98 @@
 // Copyright (C) 2024 Google LLC.
 
 //! Rust misc device sample.
+//!
+//! Below is an example userspace C program that exercises this sample's functionality.
+//!
+//! ```c
+//! #include <stdio.h>
+//! #include <stdlib.h>
+//! #include <errno.h>
+//! #include <fcntl.h>
+//! #include <unistd.h>
+//! #include <sys/ioctl.h>
+//!
+//! #define RUST_MISC_DEV_FAIL _IO('|', 0)
+//! #define RUST_MISC_DEV_HELLO _IO('|', 0x80)
+//! #define RUST_MISC_DEV_GET_VALUE _IOR('|', 0x81, int)
+//! #define RUST_MISC_DEV_SET_VALUE _IOW('|', 0x82, int)
+//!
+//! int main() {
+//!   int value, new_value;
+//!   int fd, ret;
+//!
+//!   // Open the device file
+//!   printf("Opening /dev/rust-misc-device for reading and writing\n");
+//!   fd = open("/dev/rust-misc-device", O_RDWR);
+//!   if (fd < 0) {
+//!     perror("open");
+//!     return errno;
+//!   }
+//!
+//!   // Make call into driver to say "hello"
+//!   printf("Calling Hello\n");
+//!   ret = ioctl(fd, RUST_MISC_DEV_HELLO, NULL);
+//!   if (ret < 0) {
+//!     perror("ioctl: Failed to call into Hello");
+//!     close(fd);
+//!     return errno;
+//!   }
+//!
+//!   // Get initial value
+//!   printf("Fetching initial value\n");
+//!   ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &value);
+//!   if (ret < 0) {
+//!     perror("ioctl: Failed to fetch the initial value");
+//!     close(fd);
+//!     return errno;
+//!   }
+//!
+//!   value++;
+//!
+//!   // Set value to something different
+//!   printf("Submitting new value (%d)\n", value);
+//!   ret = ioctl(fd, RUST_MISC_DEV_SET_VALUE, &value);
+//!   if (ret < 0) {
+//!     perror("ioctl: Failed to submit new value");
+//!     close(fd);
+//!     return errno;
+//!   }
+//!
+//!   // Ensure new value was applied
+//!   printf("Fetching new value\n");
+//!   ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &new_value);
+//!   if (ret < 0) {
+//!     perror("ioctl: Failed to fetch the new value");
+//!     close(fd);
+//!     return errno;
+//!   }
+//!
+//!   if (value != new_value) {
+//!     printf("Failed: Committed and retrieved values are different (%d - %d)\n", value, new_value);
+//!     close(fd);
+//!     return -1;
+//!   }
+//!
+//!   // Call the unsuccessful ioctl
+//!   printf("Attempting to call in to an non-existent IOCTL\n");
+//!   ret = ioctl(fd, RUST_MISC_DEV_FAIL, NULL);
+//!   if (ret < 0) {
+//!     perror("ioctl: Succeeded to fail - this was expected");
+//!   } else {
+//!     printf("ioctl: Failed to fail\n");
+//!     close(fd);
+//!     return -1;
+//!   }
+//!
+//!   // Close the device file
+//!   printf("Closing /dev/rust-misc-device\n");
+//!   close(fd);
+//!
+//!   printf("Success\n");
+//!   return 0;
+//! }
+//! ```
 
-/// Below is an example userspace C program that exercises this sample's functionality.
-///
-/// ```c
-/// #include <stdio.h>
-/// #include <stdlib.h>
-/// #include <errno.h>
-/// #include <fcntl.h>
-/// #include <unistd.h>
-/// #include <sys/ioctl.h>
-///
-/// #define RUST_MISC_DEV_FAIL _IO('|', 0)
-/// #define RUST_MISC_DEV_HELLO _IO('|', 0x80)
-/// #define RUST_MISC_DEV_GET_VALUE _IOR('|', 0x81, int)
-/// #define RUST_MISC_DEV_SET_VALUE _IOW('|', 0x82, int)
-///
-/// int main() {
-///   int value, new_value;
-///   int fd, ret;
-///
-///   // Open the device file
-///   printf("Opening /dev/rust-misc-device for reading and writing\n");
-///   fd = open("/dev/rust-misc-device", O_RDWR);
-///   if (fd < 0) {
-///     perror("open");
-///     return errno;
-///   }
-///
-///   // Make call into driver to say "hello"
-///   printf("Calling Hello\n");
-///   ret = ioctl(fd, RUST_MISC_DEV_HELLO, NULL);
-///   if (ret < 0) {
-///     perror("ioctl: Failed to call into Hello");
-///     close(fd);
-///     return errno;
-///   }
-///
-///   // Get initial value
-///   printf("Fetching initial value\n");
-///   ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &value);
-///   if (ret < 0) {
-///     perror("ioctl: Failed to fetch the initial value");
-///     close(fd);
-///     return errno;
-///   }
-///
-///   value++;
-///
-///   // Set value to something different
-///   printf("Submitting new value (%d)\n", value);
-///   ret = ioctl(fd, RUST_MISC_DEV_SET_VALUE, &value);
-///   if (ret < 0) {
-///     perror("ioctl: Failed to submit new value");
-///     close(fd);
-///     return errno;
-///   }
-///
-///   // Ensure new value was applied
-///   printf("Fetching new value\n");
-///   ret = ioctl(fd, RUST_MISC_DEV_GET_VALUE, &new_value);
-///   if (ret < 0) {
-///     perror("ioctl: Failed to fetch the new value");
-///     close(fd);
-///     return errno;
-///   }
-///
-///   if (value != new_value) {
-///     printf("Failed: Committed and retrieved values are different (%d - %d)\n", value, new_value);
-///     close(fd);
-///     return -1;
-///   }
-///
-///   // Call the unsuccessful ioctl
-///   printf("Attempting to call in to an non-existent IOCTL\n");
-///   ret = ioctl(fd, RUST_MISC_DEV_FAIL, NULL);
-///   if (ret < 0) {
-///     perror("ioctl: Succeeded to fail - this was expected");
-///   } else {
-///     printf("ioctl: Failed to fail\n");
-///     close(fd);
-///     return -1;
-///   }
-///
-///   // Close the device file
-///   printf("Closing /dev/rust-misc-device\n");
-///   close(fd);
-///
-///   printf("Success\n");
-///   return 0;
-/// }
-/// ```
 use core::pin::Pin;
 
 use kernel::{

---
base-commit: 7eb172143d5508b4da468ed59ee857c6e5e01da6
change-id: 20250312-rust_misc_device_tld-375d4c86e606

Best regards,
-- 
Alice Ryhl <aliceryhl@google.com>

Re: [PATCH] samples: rust_misc_device: fix markup in top-level docs

[Benno Lossin]

On Thu Mar 13, 2025 at 9:52 AM CET, Alice Ryhl wrote:
> The meaning of /// is to document the thing that comes after it, so
> currently the example is documentation for the `use core::pin::Pin;`
> statement. To write top-level docs (and have them rendered as such in
> the html by rustdoc), use //! instead.
>
> This does not change the contents of the docs at all. The only change is
> changing /// to //!.
>
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>

Good catch! I think this should have a fixes tag:

    Fixes: 8d9b095b8f89 ("samples: rust_misc_device: Provide an example C program to exercise functionality")

Reviewed-by: Benno Lossin <benno.lossin@proton.me>

---
Cheers,
Benno

> ---
>  samples/rust/rust_misc_device.rs | 181 ++++++++++++++++++++-------------------
>  1 file changed, 91 insertions(+), 90 deletions(-)

Re: [PATCH] samples: rust_misc_device: fix markup in top-level docs

[Miguel Ojeda]

On Thu, Mar 13, 2025 at 9:52 AM Alice Ryhl <aliceryhl@google.com> wrote:
>
> -/// ```
>  use core::pin::Pin;

It would be nice to catch this -- filled:

    https://github.com/rust-lang/rust-clippy/issues/14402

Cheers,
Miguel

Re: [PATCH] samples: rust_misc_device: fix markup in top-level docs

[Christian Schrefl]

On 13.03.25 9:52 AM, Alice Ryhl wrote:
> The meaning of /// is to document the thing that comes after it, so
> currently the example is documentation for the `use core::pin::Pin;`
> statement. To write top-level docs (and have them rendered as such in
> the html by rustdoc), use //! instead.
> 
> This does not change the contents of the docs at all. The only change is
> changing /// to //!.
> 
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>
> ---

Reviewed-by: Christian Schrefl <chrisi.schrefl@gmail.com>

Cheers
Christian