Fix multiple documentation issues concerned by clippy

framework/aster-frame/src/mm/dma/dma_stream.rs

@@ -125,10 +125,10 @@ impl DmaStream {
     ///
     /// This method should be called under one of the two conditions:
     /// 1. The data of the stream DMA mapping has been updated by the device side.
-    /// The CPU side needs to call the `sync` method before reading data (e.g., using [`read_bytes`]).
+    ///    The CPU side needs to call the `sync` method before reading data (e.g., using [`read_bytes`]).
     /// 2. The data of the stream DMA mapping has been updated by the CPU side
-    /// (e.g., using [`write_bytes`]).
-    /// Before the CPU side notifies the device side to read, it must call the `sync` method first.
+    ///    (e.g., using [`write_bytes`]).
+    ///    Before the CPU side notifies the device side to read, it must call the `sync` method first.
     ///
     /// [`read_bytes`]: Self::read_bytes
     /// [`write_bytes`]: Self::write_bytes

framework/aster-frame/src/mm/page_table/node.rs

@@ -15,6 +15,7 @@
 //!    - a parent page table node,
 //!    - or a handle to a page table node,
 //!    - or a processor.
+//!
 //! This is implemented by using a reference counter in the frame metadata. If the above
 //! conditions are not met, the page table node is ensured to be freed upon dropping the last
 //! reference.

framework/libs/ktest/src/lib.rs

@@ -12,7 +12,8 @@
 //! By all means, ktest is an individule crate that only requires:
 //!  - a custom linker script section `.ktest_array`,
 //!  - and an alloc implementation.
-//! to work. And the frame happens to provide both of them. Thus, any crates depending
+//!
+//! And the frame happens to provide both of them. Thus, any crates depending
 //! on the frame can use ktest without any extra dependency.
 //!
 //! ## Usage

framework/libs/linux-bzimage/setup/src/x86/amd64_efi/paging.rs

@@ -8,6 +8,7 @@
 //!  - Level-3: Page Directory Pointer Table (PDPT);
 //!  - Level-2: Page Directory (PD);
 //!  - Level-1: Page Table (PT).
+//!
 //! We sometimes use "level-n" page table to refer to the page table described
 //! above, avoiding the use of complicated names in the Intel manual.
 

kernel/aster-nix/src/process/process/mod.rs

@@ -337,8 +337,8 @@ impl Process {
     /// and moves the process to the session, returning the new session.
     ///
     /// This method may return the following errors:
-    /// * `EPERM`, if the process is a process group leader, or some existing session
-    /// or process group has the same ID as the process.
+    ///  * `EPERM`, if the process is a process group leader, or some existing session
+    ///    or process group has the same ID as the process.
     pub fn to_new_session(self: &Arc<Self>) -> Result<Arc<Session>> {
         if self.is_session_leader() {
             return Ok(self.session().unwrap());
@@ -405,14 +405,14 @@ impl Process {
 
     /// Moves the process to other process group.
     ///
-    /// * If the group already exists, the process and the group should belong to the same session.
-    /// * If the group does not exist, this method creates a new group for the process and move the
-    /// process to the group. The group is added to the session of the process.
+    ///  * If the group already exists, the process and the group should belong to the same session.
+    ///  * If the group does not exist, this method creates a new group for the process and move the
+    ///    process to the group. The group is added to the session of the process.
     ///
     /// This method may return `EPERM` in following cases:
-    /// * The process is session leader;
-    /// * The group already exists, but the group does not belong to the same session as the process;
-    /// * The group does not exist, but `pgid` is not equal to `pid` of the process.
+    ///  * The process is session leader;
+    ///  * The group already exists, but the group does not belong to the same session as the process;
+    ///  * The group does not exist, but `pgid` is not equal to `pid` of the process.
     pub fn to_other_group(self: &Arc<Self>, pgid: Pgid) -> Result<()> {
         // if the process already belongs to the process group
         if self.pgid() == pgid {

kernel/aster-nix/src/process/process_vm/init_stack/aux_vec.rs

@@ -10,10 +10,10 @@ use crate::prelude::*;
 ///
 /// Here is a concise description of Auxiliary Vector from GNU's manual:
 ///
-/// > When a program is executed, it receives information from the operating system
-/// about the environment in which it is operating. The form of this information
-/// is a table of key-value pairs, where the keys are from the set of ‘AT_’
-/// values in elf.h.
+///  > When a program is executed, it receives information from the operating system
+///  > about the environment in which it is operating. The form of this information
+///  > is a table of key-value pairs, where the keys are from the set of ‘AT_’
+///  > values in elf.h.
 
 #[allow(non_camel_case_types)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]

kernel/aster-nix/src/vm/mod.rs

@@ -3,10 +3,10 @@
 //! Virtual memory (VM).
 //!
 //! There are two primary VM abstractions:
-//! * Virtual Memory Address Regions (VMARs) a type of capability that manages
-//! user address spaces.
-//! * Virtual Memory Objects (VMOs) are are a type of capability that
-//! represents a set of memory pages.
+//!  * Virtual Memory Address Regions (VMARs) a type of capability that manages
+//!    user address spaces.
+//!  * Virtual Memory Objects (VMOs) are are a type of capability that
+//!    represents a set of memory pages.
 //!
 //! The concepts of VMARs and VMOs are originally introduced by
 //! [Zircon](https://fuchsia.dev/fuchsia-src/reference/kernel_objects/vm_object).

kernel/aster-nix/src/vm/vmar/dyn_cap.rs

@@ -47,11 +47,11 @@ impl Vmar<Rights> {
     /// # Access rights
     ///
     /// This method requires the following access rights:
-    /// 1. The VMAR contains the rights corresponding to the memory permissions of
-    /// the mapping. For example, if `perms` contains `VmPerms::WRITE`,
-    /// then the VMAR must have the Write right.
-    /// 2. Similarly, the VMO contains the rights corresponding to the memory
-    /// permissions of the mapping.  
+    ///  1. The VMAR contains the rights corresponding to the memory permissions of
+    ///     the mapping. For example, if `perms` contains `VmPerms::WRITE`,
+    ///     then the VMAR must have the Write right.
+    ///  2. Similarly, the VMO contains the rights corresponding to the memory
+    ///     permissions of the mapping.  
     ///
     /// Memory permissions may be changed through the `protect` method,
     /// which ensures that any updated memory permissions do not go beyond

kernel/aster-nix/src/vm/vmar/mod.rs

@@ -32,12 +32,12 @@ use crate::{prelude::*, vm::perms::VmPerms};
 /// whose semantics are explained below.
 ///
 /// The semantics of each access rights for VMARs are described below:
-/// * The Dup right allows duplicating a VMAR and creating children out of
-/// a VMAR.
-/// * The Read, Write, Exec rights allow creating memory mappings with
-/// readable, writable, and executable access permissions, respectively.
-/// * The Read and Write rights allow the VMAR to be read from and written to
-/// directly.
+///  * The Dup right allows duplicating a VMAR and creating children out of
+///    a VMAR.
+///  * The Read, Write, Exec rights allow creating memory mappings with
+///    readable, writable, and executable access permissions, respectively.
+///  * The Read and Write rights allow the VMAR to be read from and written to
+///    directly.
 ///
 /// VMARs are implemented with two flavors of capabilities:
 /// the dynamic one (`Vmar<Rights>`) and the static one (`Vmar<R: TRights>).

kernel/aster-nix/src/vm/vmar/vm_mapping.rs

@@ -384,12 +384,12 @@ impl VmMapping {
 
     /// Trim a range from the mapping.
     /// There are several cases.
-    /// 1. the trim_range is totally in the mapping. Then the mapping will split as two mappings.
-    /// 2. the trim_range covers the mapping. Then the mapping will be destroyed.
-    /// 3. the trim_range partly overlaps with the mapping, in left or right. Only overlapped part is trimmed.
-    /// If we create a mapping with a new map addr, we will add it to mappings_to_append.
-    /// If the mapping with map addr does not exist ever, the map addr will be added to mappings_to_remove.
-    /// Otherwise, we will directly modify self.
+    ///  1. the trim_range is totally in the mapping. Then the mapping will split as two mappings.
+    ///  2. the trim_range covers the mapping. Then the mapping will be destroyed.
+    ///  3. the trim_range partly overlaps with the mapping, in left or right. Only overlapped part is trimmed.
+    ///     If we create a mapping with a new map addr, we will add it to mappings_to_append.
+    ///     If the mapping with map addr does not exist ever, the map addr will be added to mappings_to_remove.
+    ///     Otherwise, we will directly modify self.
     pub fn trim_mapping(
         self: &Arc<Self>,
         trim_range: &Range<usize>,
@@ -674,12 +674,12 @@ impl<R1, R2> VmarMapOptions<R1, R2> {
     /// part of the mapping that is not backed by the VMO.
     /// So you may wonder: what is the point of supporting such _oversized_
     /// mappings?  The reason is two-fold.
-    /// 1. VMOs are resizable. So even if a mapping is backed by a VMO whose
-    /// size is equal to that of the mapping initially, we cannot prevent
-    /// the VMO from shrinking.
-    /// 2. Mappings are not allowed to overlap by default. As a result,
-    /// oversized mappings can serve as a placeholder to prevent future
-    /// mappings from occupying some particular address ranges accidentally.
+    ///  1. VMOs are resizable. So even if a mapping is backed by a VMO whose
+    ///     size is equal to that of the mapping initially, we cannot prevent
+    ///     the VMO from shrinking.
+    ///  2. Mappings are not allowed to overlap by default. As a result,
+    ///     oversized mappings can serve as a placeholder to prevent future
+    ///     mappings from occupying some particular address ranges accidentally.
     ///
     /// The default value is the size of the VMO.
     pub fn size(mut self, size: usize) -> Self {

kernel/aster-nix/src/vm/vmo/mod.rs

@@ -31,38 +31,38 @@ use self::options::ChildType;
 ///
 /// # Features
 ///
-/// * **I/O interface.** A VMO provides read and write methods to access the
-/// memory pages that it contain.
-/// * **On-demand paging.** The memory pages of a VMO (except for _contiguous_
-/// VMOs) are allocated lazily when the page is first accessed.
-/// * **Tree structure.** Given a VMO, one can create a child VMO from it.
-/// The child VMO can only access a subset of the parent's memory,
-/// which is a good thing for the perspective of access control.
-/// * **Copy-on-write (COW).** A child VMO may be created with COW semantics,
-/// which prevents any writes on the child from affecting the parent
-/// by duplicating memory pages only upon the first writes.
-/// * **Access control.** As capabilities, VMOs restrict the
-/// accessible range of memory and the allowed I/O operations.
-/// * **Device driver support.** If specified upon creation, VMOs will be
-/// backed by physically contiguous memory pages starting at a target address.
-/// * **File system support.** By default, a VMO's memory pages are initially
-/// all zeros. But if a VMO is attached to a pager (`Pager`) upon creation,
-/// then its memory pages will be populated by the pager.
-/// With this pager mechanism, file systems can easily implement page caches
-/// with VMOs by attaching the VMOs to pagers backed by inodes.
+///  * **I/O interface.** A VMO provides read and write methods to access the
+///    memory pages that it contain.
+///  * **On-demand paging.** The memory pages of a VMO (except for _contiguous_
+///    VMOs) are allocated lazily when the page is first accessed.
+///  * **Tree structure.** Given a VMO, one can create a child VMO from it.
+///    The child VMO can only access a subset of the parent's memory,
+///    which is a good thing for the perspective of access control.
+///  * **Copy-on-write (COW).** A child VMO may be created with COW semantics,
+///    which prevents any writes on the child from affecting the parent
+///    by duplicating memory pages only upon the first writes.
+///  * **Access control.** As capabilities, VMOs restrict the
+///    accessible range of memory and the allowed I/O operations.
+///  * **Device driver support.** If specified upon creation, VMOs will be
+///    backed by physically contiguous memory pages starting at a target address.
+///  * **File system support.** By default, a VMO's memory pages are initially
+///    all zeros. But if a VMO is attached to a pager (`Pager`) upon creation,
+///    then its memory pages will be populated by the pager.
+///    With this pager mechanism, file systems can easily implement page caches
+///    with VMOs by attaching the VMOs to pagers backed by inodes.
 ///
 /// # Capabilities
 ///
 /// As a capability, each VMO is associated with a set of access rights,
 /// whose semantics are explained below.
 ///
-/// * The Dup right allows duplicating a VMO and creating children out of
-/// a VMO.
-/// * The Read, Write, Exec rights allow creating memory mappings with
-/// readable, writable, and executable access permissions, respectively.
-/// * The Read and Write rights allow the VMO to be read from and written to
-/// directly.
-/// * The Write right allows resizing a resizable VMO.
+///  * The Dup right allows duplicating a VMO and creating children out of
+///    a VMO.
+///  * The Read, Write, Exec rights allow creating memory mappings with
+///    readable, writable, and executable access permissions, respectively.
+///  * The Read and Write rights allow the VMO to be read from and written to
+///    directly.
+///  * The Write right allows resizing a resizable VMO.
 ///
 /// VMOs are implemented with two flavors of capabilities:
 /// the dynamic one (`Vmo<Rights>`) and the static one (`Vmo<R: TRights>).
@@ -185,7 +185,7 @@ impl Pages {
 /// `Vmo_` is the structure that actually manages the content of VMO.
 /// Broadly speaking, there are two types of VMO:
 /// 1. File-backed VMO: the VMO backed by a file and resides in the `PageCache`,
-/// which includes a pager to provide it with actual pages.
+///    which includes a pager to provide it with actual pages.
 /// 2. Anonymous VMO: the VMO without a file backup, which does not have a pager.
 pub(super) struct Vmo_ {
     pager: Option<Arc<dyn Pager>>,

kernel/libs/aster-util/src/safe_ptr.rs

@@ -24,13 +24,13 @@ pub use typeflags_util::SetContain;
 /// More specifically, there are three major restrictions.
 ///
 /// 1. A safe pointer can only refer to a value of a POD type `T: Pod`,
-/// while raw pointers can do to a value of any type `T`.
+///    while raw pointers can do to a value of any type `T`.
 /// 2. A safe pointer can only refer to an address within a virtual memory object
-/// of type `M: VmIo` (e.g., VMAR and VMO), while raw pointers can do to
-/// an address within any virtual memory space.
+///    of type `M: VmIo` (e.g., VMAR and VMO), while raw pointers can do to
+///    an address within any virtual memory space.
 /// 3. A safe pointer only allows one to copy values to/from the target address,
-/// while a raw pointer allows one to borrow an immutable or mutable reference
-/// to the target address.
+///    while a raw pointer allows one to borrow an immutable or mutable reference
+///    to the target address.
 ///
 /// The expressiveness of safe pointers, although being less than that of
 /// raw pointers, is sufficient for our purpose of writing an OS kernel in safe

kernel/libs/comp-sys/component-macro/src/lib.rs

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: MPL-2.0
 
 //！This crate defines the component system related macros.
-//!
 
 #![feature(proc_macro_diagnostic)]
 #![allow(dead_code)]

kernel/libs/keyable-arc/src/lib.rs

@@ -10,9 +10,9 @@
 //!
 //! 1. It implements the `Eq` and `Hash` traits.
 //! 2. The two values of `k1` and `k2` of type `K` equal to each other,
-//! if and only if their hash values equal to each other.
+//!    if and only if their hash values equal to each other.
 //! 3. The hashes of a value of `k` of type `K` cannot change while it
-//! is in a map.
+//!    is in a map.
 //!
 //! Sometimes we want to use `Arc<T>` as the key type for a hash map but cannot do so
 //! since `T` does not satisfy the properties above. For example, a lot of types