Add doc for starry-core and apply missing_docs lint (#42)

* fix(doc): index page

* doc: add docs for core

* chore: update arceos

* chore: different `missing_docs` lint level

Author: AsakuraMizu

Makefile

@@ -10,7 +10,7 @@ export AX_LIB := axfeat
 
 RUSTDOCFLAGS := -Z unstable-options --enable-index-page -D rustdoc::broken_intra_doc_links -D missing-docs
 EXTRA_CONFIG ?= $(PWD)/configs/$(ARCH).toml
-ifneq ($(filter $(MAKECMDGOALS),doc_check_missing),) # make doc_check_missing
+ifneq ($(filter $(MAKECMDGOALS),doc),) # make doc
     export RUSTDOCFLAGS
 else ifeq ($(filter $(MAKECMDGOALS),clean user_apps ax_root),) # Not make clean, user_apps, ax_root
     export AX_TESTCASES_LIST

api/src/imp/utils/time.rs

@@ -1,7 +1,7 @@
 use arceos_posix_api::{self as api, ctypes::timeval};
 use axerrno::LinuxResult;
 use axhal::time::{monotonic_time_nanos, nanos_to_ticks};
-use starry_core::{task::time_stat_output, time::Tms};
+use starry_core::task::time_stat_output;
 
 use crate::ptr::{PtrWrapper, UserPtr};
 
@@ -13,6 +13,18 @@ pub fn sys_get_time_of_day(ts: UserPtr<timeval>) -> LinuxResult<isize> {
     unsafe { Ok(api::sys_get_time_of_day(ts.get()?) as _) }
 }
 
+#[repr(C)]
+pub struct Tms {
+    /// 进程用户态执行时间，单位为us
+    tms_utime: usize,
+    /// 进程内核态执行时间，单位为us
+    tms_stime: usize,
+    /// 子进程用户态执行时间和，单位为us
+    tms_cutime: usize,
+    /// 子进程内核态执行时间和，单位为us
+    tms_cstime: usize,
+}
+
 pub fn sys_times(tms: UserPtr<Tms>) -> LinuxResult<isize> {
     let (_, utime_us, _, stime_us) = time_stat_output();
     unsafe {

api/src/lib.rs

@@ -1,4 +1,5 @@
 #![no_std]
+#![allow(missing_docs)]
 
 #[macro_use]
 extern crate axlog;

core/src/lib.rs

@@ -1,9 +1,13 @@
+//! The core functionality of a monolithic kernel, including loading user
+//! programs and managing processes.
+
 #![no_std]
+#![warn(missing_docs)]
 
 #[macro_use]
 extern crate axlog;
 extern crate alloc;
 
 pub mod mm;
 pub mod task;
-pub mod time;
+mod time;

core/src/mm.rs

@@ -1,3 +1,5 @@
+//! User address space management.
+
 use core::ffi::CStr;
 
 use alloc::{string::String, vec};
@@ -8,6 +10,7 @@ use kernel_elf_parser::{AuxvEntry, ELFParser, app_stack_region};
 use memory_addr::{MemoryAddr, PAGE_SIZE_4K, VirtAddr};
 use xmas_elf::{ElfFile, program::SegmentData};
 
+/// Creates a new empty user address space.
 pub fn new_user_aspace_empty() -> AxResult<AddrSpace> {
     AddrSpace::new_empty(
         VirtAddr::from_usize(axconfig::plat::USER_SPACE_BASE),

core/src/task.rs

@@ -1,3 +1,5 @@
+//! User task management.
+
 use core::{
     alloc::Layout,
     cell::RefCell,
@@ -23,6 +25,7 @@ use weak_map::WeakMap;
 
 use crate::time::TimeStat;
 
+/// Create a new user task.
 pub fn new_user_task(
     name: &str,
     uctx: UspaceContext,
@@ -58,6 +61,7 @@ pub struct TaskExt {
 }
 
 impl TaskExt {
+    /// Create a new [`TaskExt`].
     pub fn new(thread: Arc<Thread>) -> Self {
         Self {
             time: RefCell::new(TimeStat::new()),
@@ -77,31 +81,36 @@ impl TaskExt {
         self.time.borrow().output()
     }
 
+    /// Get the [`ThreadData`] associated with this task.
     pub fn thread_data(&self) -> &ThreadData {
         self.thread.data().unwrap()
     }
 
+    /// Get the [`ProcessData`] associated with this task.
     pub fn process_data(&self) -> &ProcessData {
         self.thread.process().data().unwrap()
     }
 }
 
 axtask::def_task_ext!(TaskExt);
 
+/// Update the time statistics to reflect a switch from kernel mode to user mode.
 pub fn time_stat_from_kernel_to_user() {
     let curr_task = current();
     curr_task
         .task_ext()
         .time_stat_from_kernel_to_user(monotonic_time_nanos() as usize);
 }
 
+/// Update the time statistics to reflect a switch from user mode to kernel mode.
 pub fn time_stat_from_user_to_kernel() {
     let curr_task = current();
     curr_task
         .task_ext()
         .time_stat_from_user_to_kernel(monotonic_time_nanos() as usize);
 }
 
+/// Get the time statistics for the current task.
 pub fn time_stat_output() -> (usize, usize, usize, usize) {
     let curr_task = current();
     let (utime_ns, stime_ns) = curr_task.task_ext().time_stat_output();
@@ -113,6 +122,7 @@ pub fn time_stat_output() -> (usize, usize, usize, usize) {
     )
 }
 
+/// Extended data for [`Thread`].
 pub struct ThreadData {
     /// The clear thread tid field
     ///
@@ -123,23 +133,27 @@ pub struct ThreadData {
 }
 
 impl ThreadData {
+    /// Create a new [`ThreadData`].
     #[allow(clippy::new_without_default)]
     pub fn new() -> Self {
         Self {
             clear_child_tid: AtomicUsize::new(0),
         }
     }
 
+    /// Get the clear child tid field.
     pub fn clear_child_tid(&self) -> usize {
         self.clear_child_tid.load(Ordering::Relaxed)
     }
 
+    /// Set the clear child tid field.
     pub fn set_clear_child_tid(&self, clear_child_tid: usize) {
         self.clear_child_tid
             .store(clear_child_tid, Ordering::Relaxed);
     }
 }
 
+/// Extended data for [`Process`].
 pub struct ProcessData {
     /// The executable path
     pub exe_path: RwLock<String>,
@@ -154,6 +168,7 @@ pub struct ProcessData {
 }
 
 impl ProcessData {
+    /// Create a new [`ProcessData`].
     pub fn new(exe_path: String, aspace: Arc<Mutex<AddrSpace>>) -> Self {
         Self {
             exe_path: RwLock::new(exe_path),
@@ -164,18 +179,22 @@ impl ProcessData {
         }
     }
 
+    /// Get the bottom address of the user heap.
     pub fn get_heap_bottom(&self) -> usize {
         self.heap_bottom.load(Ordering::Acquire)
     }
 
+    /// Set the bottom address of the user heap.
     pub fn set_heap_bottom(&self, bottom: usize) {
         self.heap_bottom.store(bottom, Ordering::Release)
     }
 
+    /// Get the top address of the user heap.
     pub fn get_heap_top(&self) -> usize {
         self.heap_top.load(Ordering::Acquire)
     }
 
+    /// Set the top address of the user heap.
     pub fn set_heap_top(&self, top: usize) {
         self.heap_top.store(top, Ordering::Release)
     }
@@ -221,6 +240,8 @@ static PROCESS_TABLE: RwLock<WeakMap<Pid, Weak<Process>>> = RwLock::new(WeakMap:
 static PROCESS_GROUP_TABLE: RwLock<WeakMap<Pid, Weak<ProcessGroup>>> = RwLock::new(WeakMap::new());
 static SESSION_TABLE: RwLock<WeakMap<Pid, Weak<Session>>> = RwLock::new(WeakMap::new());
 
+/// Add the thread and possibly its process, process group and session to the
+/// corresponding tables.
 pub fn add_thread_to_table(thread: &Arc<Thread>) {
     let mut thread_table = THREAD_TABLE.write();
     thread_table.insert(thread.tid(), thread);

core/src/time.rs

@@ -1,15 +1,3 @@
-#[repr(C)]
-pub struct Tms {
-    /// 进程用户态执行时间，单位为us
-    pub tms_utime: usize,
-    /// 进程内核态执行时间，单位为us
-    pub tms_stime: usize,
-    /// 子进程用户态执行时间和，单位为us
-    pub tms_cutime: usize,
-    /// 子进程内核态执行时间和，单位为us
-    pub tms_cstime: usize,
-}
-
 numeric_enum_macro::numeric_enum! {
     #[repr(i32)]
     #[allow(non_camel_case_types)]