Merge pull request rcore-os#168 from xxchan/master

crate level deny(missing_docs) for zircon_object

zircon-object/src/debuglog.rs

@@ -1,3 +1,4 @@
+//! Objects for Kernel Debuglog.
 use {
     super::*,
     crate::object::*,
@@ -13,6 +14,11 @@ lazy_static! {
     });
 }
 
+/// Debuglog - Kernel debuglog
+///
+/// ## SYNOPSIS
+///
+/// Debuglog objects allow userspace to read and write to kernel debug logs.
 pub struct DebugLog {
     base: KObjectBase,
     flags: u32,
@@ -63,6 +69,8 @@ struct DlogHeader {
     tid: u64,
 }
 
+/// Log entry severity. Used for coarse filtering of log messages.
+#[allow(missing_docs)]
 #[repr(u8)]
 #[derive(Debug)]
 pub enum Severity {
@@ -75,6 +83,7 @@ pub enum Severity {
 }
 
 const HEADER_SIZE: usize = core::mem::size_of::<DlogHeader>();
+/// Max length of Dlog read buffer.
 pub const DLOG_MAX_LEN: usize = 256;
 
 #[allow(unsafe_code)]

zircon-object/src/dev/mod.rs

@@ -1,5 +1,4 @@
 //! Objects for Device Drivers.
-#![deny(missing_docs)]
 use super::*;
 
 mod bti;

zircon-object/src/error.rs

@@ -11,6 +11,7 @@ pub type ZxResult<T = ()> = Result<T, ZxError>;
 #[repr(i32)]
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
 pub enum ZxError {
+    /// Success.
     OK = 0,
 
     // ======= Internal failures =======

zircon-object/src/hypervisor/mod.rs

@@ -1,4 +1,3 @@
-#![deny(missing_docs)]
 //! Objects for Virtual Machine Monitor (hypervisor).
 
 mod guest;

zircon-object/src/ipc/mod.rs

@@ -1,4 +1,3 @@
-#![deny(missing_docs)]
 //! Objects for IPC.
 
 mod channel;

zircon-object/src/lib.rs

@@ -6,7 +6,7 @@
 //! - `hypervisor`: Enables `zircon_object::hypervisor` (`Guest` and `Vcpu`).
 
 #![no_std]
-#![deny(warnings, unsafe_code, unused_must_use)]
+#![deny(warnings, unsafe_code, unused_must_use, missing_docs)]
 #![feature(asm)]
 #![feature(linkage)]
 #![feature(drain_filter)]

zircon-object/src/object/mod.rs

@@ -1,4 +1,3 @@
-#![deny(missing_docs)]
 //! Kernel object basis.
 //!
 //! # Create new kernel object

zircon-object/src/signal/mod.rs

@@ -1,4 +1,3 @@
-#![deny(missing_docs)]
 //! Objects for signaling and waiting.
 
 use super::*;

zircon-object/src/task/mod.rs

@@ -1,4 +1,3 @@
-#![deny(missing_docs)]
 //! Objects for Task Management.
 
 use super::*;

zircon-object/src/util/elf_loader.rs

@@ -1,3 +1,4 @@
+//! ELF loading of Zircon and Linux.
 use crate::{error::*, vm::*};
 use alloc::sync::Arc;
 use xmas_elf::{
@@ -7,14 +8,16 @@ use xmas_elf::{
     ElfFile,
 };
 
+/// Extensional ELF loading methods for `VmAddressRegion`.
 pub trait VmarExt {
+    /// Create `VMObject` from all LOAD segments of `elf` and map them to this VMAR.
+    /// Return the first `VMObject`.
     fn load_from_elf(&self, elf: &ElfFile) -> ZxResult<Arc<VmObject>>;
+    /// Same as `load_from_elf`, but the `vmo` is an existing one instead of a lot of new ones.
     fn map_from_elf(&self, elf: &ElfFile, vmo: Arc<VmObject>) -> ZxResult;
 }
 
 impl VmarExt for VmAddressRegion {
-    /// Create `VMObject` from all LOAD segments of `elf` and map them to this VMAR.
-    /// Return the first `VMObject`.
     fn load_from_elf(&self, elf: &ElfFile) -> ZxResult<Arc<VmObject>> {
         let mut first_vmo = None;
         for ph in elf.program_iter() {
@@ -29,7 +32,6 @@ impl VmarExt for VmAddressRegion {
         }
         Ok(first_vmo.unwrap())
     }
-
     fn map_from_elf(&self, elf: &ElfFile, vmo: Arc<VmObject>) -> ZxResult {
         for ph in elf.program_iter() {
             if ph.get_type().unwrap() != Type::Load {
@@ -78,16 +80,21 @@ fn make_vmo(elf: &ElfFile, ph: ProgramHeader) -> ZxResult<Arc<VmObject>> {
     Ok(vmo)
 }
 
+/// Extensional ELF loading methods for `ElfFile`.
 pub trait ElfExt {
+    /// Get total size of all LOAD segments.
     fn load_segment_size(&self) -> usize;
+    /// Get address of the given `symbol`.
     fn get_symbol_address(&self, symbol: &str) -> Option<u64>;
+    /// Get the program interpreter path name.
     fn get_interpreter(&self) -> Result<&str, &str>;
+    /// Get the symbol table for dynamic linking (.dynsym section).
     fn dynsym(&self) -> Result<&[DynEntry64], &'static str>;
+    /// Relocate according to the dynamic relocation section (.rel.dyn section).
     fn relocate(&self, base: usize) -> Result<(), &'static str>;
 }
 
 impl ElfExt for ElfFile<'_> {
-    /// Get total size of all LOAD segments.
     fn load_segment_size(&self) -> usize {
         self.program_iter()
             .filter(|ph| ph.get_type().unwrap() == Type::Load)
@@ -97,7 +104,6 @@ impl ElfExt for ElfFile<'_> {
             * PAGE_SIZE
     }
 
-    /// Get address of the given `symbol`.
     fn get_symbol_address(&self, symbol: &str) -> Option<u64> {
         for section in self.section_iter() {
             if let SectionData::SymbolTable64(entries) = section.get_data(self).unwrap() {

zircon-object/src/util/kcounter.rs

@@ -1,3 +1,4 @@
+//! Kernel counter.
 use core::fmt::{Debug, Error, Formatter};
 use core::sync::atomic::{AtomicUsize, Ordering};
 
@@ -23,9 +24,12 @@ impl KCounter {
     }
 }
 
+/// Kernel counter descriptor.
 #[repr(C)]
 pub struct KCounterDescriptor {
+    /// The counter.
     pub counter: &'static KCounter,
+    /// The counter's name.
     pub name: &'static str,
 }
 
@@ -48,6 +52,7 @@ macro_rules! kcounter {
     };
 }
 
+/// Kernel counter descriptor array.
 pub struct KCounterDescriptorArray(pub &'static [KCounterDescriptor]);
 
 impl KCounterDescriptorArray {

zircon-object/src/util/mod.rs

@@ -1,4 +1,5 @@
-pub mod block_range;
+//! Utilities.
+pub(crate) mod block_range;
 #[cfg(feature = "elf")]
 pub mod elf_loader;
 pub mod kcounter;

zircon-object/src/vm/mod.rs

@@ -1,4 +1,3 @@
-#![deny(missing_docs)]
 //! Objects for Virtual Memory Management.
 
 mod stream;