Merge pull request #672 from ojeda/style

treewide: update/normalize comment style

Author: ojeda

Documentation/rust/coding-guidelines.rst

@@ -74,7 +74,7 @@ This is how a well-documented Rust function may look like::
 		match self {
 			Some(val) => val,
 
-			// SAFETY: the safety contract must be upheld by the caller.
+			// SAFETY: The safety contract must be upheld by the caller.
 			None => unsafe { hint::unreachable_unchecked() },
 		}
 	}

rust/kernel/bindings.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: GPL-2.0
 
-//! Bindings
+//! Bindings.
 //!
 //! Imports the generated bindings by `bindgen`.
 

rust/kernel/chrdev.rs

@@ -23,9 +23,9 @@ use crate::str::CStr;
 ///
 /// # Invariants
 ///
-/// - [`self.0`] is valid and non-null.
-/// - [`(*self.0).ops`] is valid, non-null and has static lifetime.
-/// - [`(*self.0).owner`] is valid and, if non-null, has module lifetime.
+///   - [`self.0`] is valid and non-null.
+///   - [`(*self.0).ops`] is valid, non-null and has static lifetime.
+///   - [`(*self.0).owner`] is valid and, if non-null, has module lifetime.
 struct Cdev(*mut bindings::cdev);
 
 impl Cdev {
@@ -45,20 +45,20 @@ impl Cdev {
             (*cdev).owner = module.0;
         }
         // INVARIANTS:
-        // - [`self.0`] is valid and non-null.
-        // - [`(*self.0).ops`] is valid, non-null and has static lifetime,
-        //   because it was coerced from a reference with static lifetime.
-        // - [`(*self.0).owner`] is valid and, if non-null, has module lifetime,
-        //   guaranteed by the [`ThisModule`] invariant.
+        //   - [`self.0`] is valid and non-null.
+        //   - [`(*self.0).ops`] is valid, non-null and has static lifetime,
+        //     because it was coerced from a reference with static lifetime.
+        //   - [`(*self.0).owner`] is valid and, if non-null, has module lifetime,
+        //     guaranteed by the [`ThisModule`] invariant.
         Ok(Self(cdev))
     }
 
     fn add(&mut self, dev: bindings::dev_t, count: c_types::c_uint) -> Result {
-        // SAFETY: according to the type invariants:
-        // - [`self.0`] can be safely passed to [`bindings::cdev_add`].
-        // - [`(*self.0).ops`] will live at least as long as [`self.0`].
-        // - [`(*self.0).owner`] will live at least as long as the
-        //   module, which is an implicit requirement.
+        // SAFETY: According to the type invariants:
+        //   - [`self.0`] can be safely passed to [`bindings::cdev_add`].
+        //   - [`(*self.0).ops`] will live at least as long as [`self.0`].
+        //   - [`(*self.0).owner`] will live at least as long as the
+        //     module, which is an implicit requirement.
         let rc = unsafe { bindings::cdev_add(self.0, dev, count) };
         if rc != 0 {
             return Err(Error::from_kernel_errno(rc));

rust/kernel/clk.rs

@@ -26,23 +26,23 @@ impl Clk {
 
     /// Returns value of the rate field of `struct clk`.
     pub fn get_rate(&self) -> usize {
-        // SAFETY: the pointer is valid by the type invariant.
+        // SAFETY: The pointer is valid by the type invariant.
         unsafe { bindings::clk_get_rate(self.0) as usize }
     }
 
     /// Prepares and enables the underlying hardware clock.
     ///
     /// This function should not be called in atomic context.
     pub fn prepare_enable(self) -> Result<EnabledClk> {
-        // SAFETY: the pointer is valid by the type invariant.
+        // SAFETY: The pointer is valid by the type invariant.
         to_result(|| unsafe { bindings::clk_prepare_enable(self.0) })?;
         Ok(EnabledClk(self))
     }
 }
 
 impl Drop for Clk {
     fn drop(&mut self) {
-        // SAFETY: the pointer is valid by the type invariant.
+        // SAFETY: The pointer is valid by the type invariant.
         unsafe { bindings::clk_put(self.0) };
     }
 }
@@ -61,15 +61,15 @@ impl EnabledClk {
     /// This function should not be called in atomic context.
     pub fn disable_unprepare(self) -> Clk {
         let mut clk = ManuallyDrop::new(self);
-        // SAFETY: the pointer is valid by the type invariant.
+        // SAFETY: The pointer is valid by the type invariant.
         unsafe { bindings::clk_disable_unprepare(clk.0 .0) };
         core::mem::replace(&mut clk.0, Clk(core::ptr::null_mut()))
     }
 }
 
 impl Drop for EnabledClk {
     fn drop(&mut self) {
-        // SAFETY: the pointer is valid by the type invariant.
+        // SAFETY: The pointer is valid by the type invariant.
         unsafe { bindings::clk_disable_unprepare(self.0 .0) };
     }
 }

rust/kernel/device.rs

@@ -61,11 +61,11 @@ pub unsafe trait RawDevice {
             None => core::ptr::null(),
         };
 
-        // SAFETY: id_ptr is optional and may be either a valid pointer
+        // SAFETY: `id_ptr` is optional and may be either a valid pointer
         // from the type invariant or NULL otherwise.
         let clk_ptr = unsafe { from_kernel_err_ptr(bindings::clk_get(self.raw_device(), id_ptr)) }?;
 
-        // SAFETY: clock is initialized with valid pointer returned from `bindings::clk_get` call.
+        // SAFETY: Clock is initialized with valid pointer returned from `bindings::clk_get` call.
         unsafe { Ok(Clk::new(clk_ptr)) }
     }
 
@@ -222,10 +222,10 @@ impl Drop for Device {
 /// some device state must be freed and not used anymore, while others must remain accessible.
 ///
 /// This struct separates the device data into three categories:
-/// 1. Registrations: are destroyed when the device is removed, but before the io resources
-///    become inaccessible.
-/// 2. Io resources: are available until the device is removed.
-/// 3. General data: remain available as long as the ref count is nonzero.
+///   1. Registrations: are destroyed when the device is removed, but before the io resources
+///      become inaccessible.
+///   2. Io resources: are available until the device is removed.
+///   3. General data: remain available as long as the ref count is nonzero.
 ///
 /// This struct implements the `DeviceRemoval` trait so that it can clean resources up even if not
 /// explicitly called by the device drivers.

rust/kernel/driver.rs

@@ -116,8 +116,8 @@ impl<T: DriverOps> Drop for Registration<T> {
 /// # Safety
 ///
 /// Implementers must ensure that:
-///   * [`RawDeviceId::ZERO`] is actually a zeroed-out version of the raw device id.
-///   * [`RawDeviceId::to_rawid`] stores `offset` in the context/data field of the raw device id so
+///   - [`RawDeviceId::ZERO`] is actually a zeroed-out version of the raw device id.
+///   - [`RawDeviceId::to_rawid`] stores `offset` in the context/data field of the raw device id so
 ///     that buses can recover the pointer to the data.
 pub unsafe trait RawDeviceId {
     /// The raw type that holds the device id.

rust/kernel/error.rs

@@ -324,15 +324,15 @@ impl Error {
     /// be returned in such a case.
     pub(crate) fn from_kernel_errno(errno: c_types::c_int) -> Error {
         if errno < -(bindings::MAX_ERRNO as i32) || errno >= 0 {
-            // TODO: make it a `WARN_ONCE` once available.
+            // TODO: Make it a `WARN_ONCE` once available.
             crate::pr_warn!(
                 "attempted to create `Error` with out of range `errno`: {}",
                 errno
             );
             return Error::EINVAL;
         }
 
-        // INVARIANT: the check above ensures the type invariant
+        // INVARIANT: The check above ensures the type invariant
         // will hold.
         Error(errno)
     }
@@ -343,7 +343,7 @@ impl Error {
     ///
     /// `errno` must be within error code range (i.e. `>= -MAX_ERRNO && < 0`).
     pub(crate) unsafe fn from_kernel_errno_unchecked(errno: c_types::c_int) -> Error {
-        // INVARIANT: the contract ensures the type invariant
+        // INVARIANT: The contract ensures the type invariant
         // will hold.
         Error(errno)
     }
@@ -507,24 +507,24 @@ pub(crate) use from_kernel_result;
 ///     }
 /// }
 /// ```
-// TODO: remove `dead_code` marker once an in-kernel client is available.
+// TODO: Remove `dead_code` marker once an in-kernel client is available.
 #[allow(dead_code)]
 pub(crate) fn from_kernel_err_ptr<T>(ptr: *mut T) -> Result<*mut T> {
-    // CAST: casting a pointer to `*const c_types::c_void` is always valid.
+    // CAST: Casting a pointer to `*const c_types::c_void` is always valid.
     let const_ptr: *const c_types::c_void = ptr.cast();
-    // SAFETY: the FFI function does not deref the pointer.
+    // SAFETY: The FFI function does not deref the pointer.
     if unsafe { bindings::IS_ERR(const_ptr) } {
-        // SAFETY: the FFI function does not deref the pointer.
+        // SAFETY: The FFI function does not deref the pointer.
         let err = unsafe { bindings::PTR_ERR(const_ptr) };
-        // CAST: if `IS_ERR()` returns `true`,
+        // CAST: If `IS_ERR()` returns `true`,
         // then `PTR_ERR()` is guaranteed to return a
         // negative value greater-or-equal to `-bindings::MAX_ERRNO`,
         // which always fits in an `i16`, as per the invariant above.
         // And an `i16` always fits in an `i32`. So casting `err` to
         // an `i32` can never overflow, and is always valid.
         //
         // SAFETY: `IS_ERR()` ensures `err` is a
-        // negative value greater-or-equal to `-bindings::MAX_ERRNO`
+        // negative value greater-or-equal to `-bindings::MAX_ERRNO`.
         return Err(unsafe { Error::from_kernel_errno_unchecked(err as i32) });
     }
     Ok(ptr)

rust/kernel/file_operations.rs

@@ -711,7 +711,7 @@ pub trait FileOperations {
     /// Maps areas of the caller's virtual memory with device/file memory.
     ///
     /// Corresponds to the `mmap` function pointer in `struct file_operations`.
-    /// TODO: wrap `vm_area_struct` so that we don't have to expose it.
+    /// TODO: Wrap `vm_area_struct` so that we don't have to expose it.
     fn mmap(
         _this: <Self::Wrapper as PointerWrapper>::Borrowed<'_>,
         _file: &File,

rust/kernel/miscdev.rs

@@ -194,7 +194,7 @@ impl<T: FileOperations> FileOpenAdapter<T::OpenData> for Registration<T> {
         _inode: *mut bindings::inode,
         file: *mut bindings::file,
     ) -> *const T::OpenData {
-        // SAFETY: the caller must guarantee that `file` is valid.
+        // SAFETY: The caller must guarantee that `file` is valid.
         let reg = crate::container_of!(unsafe { (*file).private_data }, Self, mdev);
 
         // SAFETY: This function is only called while the misc device is still registered, so the

rust/kernel/rbtree.rs

@@ -322,7 +322,7 @@ impl<K, V> RBTree<K, V> {
     where
         K: Ord,
     {
-        // SAFETY: the `find` return value is a node in the tree, so it is valid.
+        // SAFETY: The `find` return value is a node in the tree, so it is valid.
         self.find(key)
             .map(|mut node| unsafe { &mut node.as_mut().value })
     }
@@ -336,13 +336,13 @@ impl<K, V> RBTree<K, V> {
     {
         let mut node = self.find(key)?;
 
-        // SAFETY: the `find` return value is a node in the tree, so it is valid.
+        // SAFETY: The `find` return value is a node in the tree, so it is valid.
         unsafe { bindings::rb_erase(&mut node.as_mut().links, &mut self.root) };
 
         // INVARIANT: The node is being returned and the caller may free it, however, it was
         // removed from the tree. So the invariants still hold.
         Some(RBTreeNode {
-            // SAFETY: the `find` return value was a node in the tree, so it is valid.
+            // SAFETY: The `find` return value was a node in the tree, so it is valid.
             node: unsafe { Box::from_raw(node.as_ptr()) },
         })
     }