Add missing docs for the rest of the code base (merge after #1026) (#1028)

This is the last PR for adding missing docs, and it closes
#309. All the public items
should be documented properly now, and `#![deny(missing_docs)]` is used
so any new public item that does not have rustdoc will cause the build
to fail.

Author: qinsoon

.github/scripts/ci-doc.sh

@@ -4,7 +4,7 @@
 # If the output path is changed in this script, we need to update rustdoc.yml as well.
 
 # deny warnings for rustdoc
-export RUSTDOCFLAGS="-D warnings"
+export RUSTDOCFLAGS="-D warnings -D missing_docs"
 
 # Check cargo doc
 # We document public and private items for MMTk developers (GC implementers).

docs/userguide/src/tutorial/code/mygc_semispace/global.rs

@@ -44,9 +44,6 @@ pub struct MyGC<VM: VMBinding> {
 // ANCHOR: constraints
 pub const MYGC_CONSTRAINTS: PlanConstraints = PlanConstraints {
     moves_objects: true,
-    gc_header_bits: 2,
-    gc_header_words: 0,
-    num_specialized_scans: 1,
     ..PlanConstraints::default()
 };
 // ANCHOR_END: constraints

docs/userguide/src/tutorial/code/mygc_semispace/mod.rs

@@ -1,5 +1,7 @@
 // This module's code is unused When we compile this module with MMTk core. Allow it.
 #![allow(dead_code)]
+// Allow missing docs for public items in this module.
+#![allow(missing_docs)]
 
 mod gc_work; // Add
 mod global;

docs/userguide/src/tutorial/mygc/ss/alloc.md

@@ -18,7 +18,6 @@ We will make the following changes:
 
 1. Initialize `gc_header_bits` to 2. We reserve 2 bits in the header for GC use.
 1. Initialize `moves_objects` to `true`.
-1. Initialize `num_specialized_scans` to 1.
 
 Finished code (step 1-3):
 ```

src/build_info.rs

@@ -1,3 +1,5 @@
+//! Some information for the current MMTk build.
+
 mod raw {
     // This includes a full list of the constants in built.rs generated by the 'built' crate.
     // https://docs.rs/built/latest/built/index.html

src/lib.rs

@@ -1,6 +1,3 @@
-// TODO: We should fix missing docs for public items and turn this on (Issue #309).
-// #![deny(missing_docs)]
-
 // Allow this for now. Clippy suggests we should use Sft, Mmtk, rather than SFT and MMTK.
 // According to its documentation (https://rust-lang.github.io/rust-clippy/master/index.html#upper_case_acronyms),
 // with upper-case-acronyms-aggressive turned on, it should also warn us about SFTMap, VMBinding, GCWorker.
@@ -69,4 +66,3 @@ pub mod vm;
 pub use crate::plan::{
     AllocationSemantics, BarrierSelector, Mutator, MutatorContext, ObjectQueue, Plan,
 };
-pub use crate::policy::copy_context::PolicyCopyContext;

src/memory_manager.rs

@@ -434,6 +434,7 @@ pub fn free_with_size<VM: VMBinding>(mmtk: &MMTK<VM>, addr: Address, old_size: u
     crate::util::malloc::free_with_size(mmtk, addr, old_size)
 }
 
+/// Get the current active malloc'd bytes. Here MMTk only accounts for bytes that are done through those 'counted malloc' functions.
 #[cfg(feature = "malloc_counted_size")]
 pub fn get_malloc_bytes<VM: VMBinding>(mmtk: &MMTK<VM>) -> usize {
     mmtk.state.malloc_bytes.load(Ordering::SeqCst)

src/mmtk.rs

@@ -50,7 +50,7 @@ use crate::util::rust_util::InitializeOnce;
 // A global space function table that allows efficient dispatch space specific code for addresses in our heap.
 pub static SFT_MAP: InitializeOnce<Box<dyn SFTMap>> = InitializeOnce::new();
 
-// MMTk builder. This is used to set options before actually creating an MMTk instance.
+/// MMTk builder. This is used to set options and other settings before actually creating an MMTk instance.
 pub struct MMTKBuilder {
     /// The options for this instance.
     pub options: Options,
@@ -131,7 +131,8 @@ unsafe impl<VM: VMBinding> Sync for MMTK<VM> {}
 unsafe impl<VM: VMBinding> Send for MMTK<VM> {}
 
 impl<VM: VMBinding> MMTK<VM> {
-    pub fn new(options: Arc<Options>) -> Self {
+    /// Create an MMTK instance. This is not public. Bindings should use [`MMTKBuilder::build`].
+    pub(crate) fn new(options: Arc<Options>) -> Self {
         // Initialize SFT first in case we need to use this in the constructor.
         // The first call will initialize SFT map. Other calls will be blocked until SFT map is initialized.
         crate::policy::sft_map::SFTRefStorage::pre_use_check();
@@ -219,6 +220,9 @@ impl<VM: VMBinding> MMTK<VM> {
         }
     }
 
+    /// Generic hook to allow benchmarks to be harnessed. MMTk will trigger a GC
+    /// to clear any residual garbage and start collecting statistics for the benchmark.
+    /// This is usually called by the benchmark harness as its last step before the actual benchmark.
     pub fn harness_begin(&self, tls: VMMutatorThread) {
         probe!(mmtk, harness_begin);
         self.handle_user_collection_request(tls, true, true);
@@ -227,6 +231,9 @@ impl<VM: VMBinding> MMTK<VM> {
         self.scheduler.enable_stat();
     }
 
+    /// Generic hook to allow benchmarks to be harnessed. MMTk will stop collecting
+    /// statistics, and print out the collected statistics in a defined format.
+    /// This is usually called by the benchmark harness right after the actual benchmark.
     pub fn harness_end(&'static self) {
         self.stats.stop_all(self);
         self.inside_harness.store(false, Ordering::SeqCst);
@@ -264,10 +271,12 @@ impl<VM: VMBinding> MMTK<VM> {
         }
     }
 
+    /// Return true if a collection is in progress.
     pub fn gc_in_progress(&self) -> bool {
         *self.state.gc_status.lock().unwrap() != GcStatus::NotInGC
     }
 
+    /// Return true if a collection is in progress and past the preparatory stage.
     pub fn gc_in_progress_proper(&self) -> bool {
         *self.state.gc_status.lock().unwrap() == GcStatus::GcProper
     }
@@ -338,6 +347,7 @@ impl<VM: VMBinding> MMTK<VM> {
         self.gc_requester.request();
     }
 
+    /// Get a reference to the plan.
     pub fn get_plan(&self) -> &dyn Plan<VM = VM> {
         unsafe { &**(self.plan.get()) }
     }
@@ -352,6 +362,7 @@ impl<VM: VMBinding> MMTK<VM> {
         &mut **(self.plan.get())
     }
 
+    /// Get the run time options.
     pub fn get_options(&self) -> &Options {
         &self.options
     }

src/plan/barriers.rs

@@ -17,11 +17,14 @@ use downcast_rs::Downcast;
 /// VM bindings may also use this to enable the correct fast-path, if the fast-path is implemented in the binding.
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub enum BarrierSelector {
+    /// No barrier is used.
     NoBarrier,
+    /// Object remembering barrier is used.
     ObjectBarrier,
 }
 
 impl BarrierSelector {
+    /// A const function to check if two barrier selectors are the same.
     pub const fn equals(&self, other: BarrierSelector) -> bool {
         // cast enum to u8 then compare. Otherwise, we cannot do it in a const fn.
         *self as u8 == other as u8

src/plan/generational/copying/global.rs

@@ -40,6 +40,7 @@ pub struct GenCopy<VM: VMBinding> {
     pub copyspace1: CopySpace<VM>,
 }
 
+/// The plan constraints for the generational copying plan.
 pub const GENCOPY_CONSTRAINTS: PlanConstraints = crate::plan::generational::GEN_CONSTRAINTS;
 
 impl<VM: VMBinding> Plan for GenCopy<VM> {