Fix some documentation issues (#716)

 - Fix outdated text in tutorial
 - Deny warnings in ci-doc
 - Fix some links in rustdoc

Author: qinsoon

.github/scripts/ci-doc.sh

@@ -3,6 +3,9 @@
 # rustdoc.yml will copy the docs from respective directories to a directory for publishing.
 # If the output path is changed in this script, we need to update rustdoc.yml as well.
 
+# deny warnings for rustdoc
+export RUSTFLAGS="-D warnings"
+
 # Check cargo doc
 # We generate two versions of docs: one with only public items for binding developers for our API, and
 # the other with both public and private items for MMTk developers (GC implementers).

docs/tutorial/code/mygc_semispace/gc_work.rs

@@ -25,7 +25,7 @@ impl<VM: VMBinding> crate::scheduler::GCWorkContext for MyGCWorkContext2<VM> {
 }
 // ANCHOR: workcontext_plan
 
-use crate::util::{Address, ObjectReference};
+use crate::util::ObjectReference;
 use crate::util::copy::CopySemantics;
 use crate::MMTK;
 use crate::policy::space::Space;

docs/tutorial/code/mygc_semispace/global.rs

@@ -13,17 +13,12 @@ use crate::policy::space::Space;
 use crate::scheduler::*; // Modify
 use crate::util::alloc::allocators::AllocatorSelector;
 use crate::util::copy::*;
-use crate::util::heap::layout::heap_layout::Mmapper;
-use crate::util::heap::layout::heap_layout::VMMap;
-use crate::util::heap::HeapMeta;
 use crate::util::heap::VMRequest;
 use crate::util::metadata::side_metadata::{SideMetadataSanity, SideMetadataContext};
-use crate::util::options::Options;
 use crate::util::opaque_pointer::*;
 use crate::vm::VMBinding;
 use enum_map::EnumMap;
 use std::sync::atomic::{AtomicBool, Ordering}; // Add
-use std::sync::Arc;
 // ANCHOR_END: imports_no_gc_work
 
 // Remove #[allow(unused_imports)].

docs/tutorial/code/mygc_semispace/mod.rs

@@ -1,3 +1,6 @@
+// This module's code is unused When we compile this module with MMTk core. Allow it.
+#![allow(dead_code)]
+
 mod gc_work; // Add
 mod global;
 mod mutator;

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

@@ -66,6 +66,15 @@ Finished code (step 2):
 {{#include ../../../code/mygc_semispace/global.rs:plan_def}}
 ```
 
+Note that we have attributes on some fields. These attributes tell MMTk's macros on
+how to generate code to trace objects in this plan. Although there are other approaches that
+you can implement object tracing, in this tutorial we use the macros, as it is the simplest.
+Make sure you import the macros. We will discuss on what those attributes mean in later sections.
+
+```rust
+use mmtk_macros::PlanTraceObject;
+```
+
 ### Implement the Plan trait for MyGC
 
 #### Constructor
@@ -88,16 +97,6 @@ that you just defined.
 {{#include ../../../code/mygc_semispace/global.rs:plan_new}}
 ```
 
-#### Initializer
-
-Find `gc_init()`. Change it to initialise the common plan and the two 
-copyspaces, rather than the base plan and mygc_space. The contents of the 
-initializer calls are identical.
-
-```rust
-{{#include ../../../code/mygc_semispace/global.rs:gc_init}}
-```
-
 ### Access MyGC spaces
 
 Add a new section of methods for MyGC:

src/memory_manager.rs

@@ -28,17 +28,17 @@ use crate::vm::ReferenceGlue;
 use crate::vm::VMBinding;
 use std::sync::atomic::Ordering;
 
-/// Initialize an MMTk instance. A VM should call this method after creating an [MMTK](../mmtk/struct.MMTK.html)
+/// Initialize an MMTk instance. A VM should call this method after creating an [`crate::MMTK`]
 /// instance but before using any of the methods provided in MMTk (except `process()` and `process_bulk()`).
 ///
 /// We expect a binding to ininitialize MMTk in the following steps:
 ///
-/// 1. Create an [MMTKBuilder](../mmtk/struct.MMTKBuilder.html) instance.
-/// 2. Set command line options for MMTKBuilder by [process()](./fn.process.html) or [process_bulk()](./fn.process_bulk.html).
+/// 1. Create an [`crate::MMTKBuilder`] instance.
+/// 2. Set command line options for MMTKBuilder by [`crate::memory_manager::process`] or [`crate::memory_manager::process_bulk`].
 /// 3. Initialize MMTk by calling this function, `mmtk_init()`, and pass the builder earlier. This call will return an MMTK instance.
 ///    Usually a binding store the MMTK instance statically as a singleton. We plan to allow multiple instances, but this is not yet fully
 ///    supported. Currently we assume a binding will only need one MMTk instance.
-/// 4. Enable garbage collection in MMTk by [enable_collection()](./fn.enable_collection.html). A binding should only call this once its
+/// 4. Enable garbage collection in MMTk by [`crate::memory_manager::enable_collection`]. A binding should only call this once its
 ///    thread system is ready. MMTk will not trigger garbage collection before this call.
 ///
 /// Note that this method will attempt to initialize a logger. If the VM would like to use its own logger, it should initialize the logger before calling this method.

src/plan/global.rs

@@ -1027,7 +1027,7 @@ pub enum AllocationSemantics {
     Immortal = 1,
     /// Large objects. It is usually desirable to allocate large objects specially. Large objects
     /// are allocated with page granularity and will not be moved.
-    /// Each plan provides `max_non_los_default_alloc_bytes` (see [`crate::plan::plan_constraints::PlanConstraints`]),
+    /// Each plan provides `max_non_los_default_alloc_bytes` (see [`crate::plan::PlanConstraints`]),
     /// which defines a threshold for objects that can be allocated with the default semantic. Any object that is larger than the
     /// threshold must be allocated with the `Los` semantic.
     /// This semantic may get removed and MMTk will transparently allocate into large object space for large objects.

src/policy/copy_context.rs

@@ -9,7 +9,7 @@ use crate::vm::VMBinding;
 /// mature space is ImmixSpace. When we copy from nursery to mature, ImmixCopyContext should be
 /// used.
 /// Note that this trait should only be implemented with policy specific behaviors. Please
-/// refer to [GCWorkerCopyContext](util/copy/struct.GCWorkerCopyContext.html) which implements common
+/// refer to [`crate::util::copy::GCWorkerCopyContext`] which implements common
 /// behaviors for copying.
 pub trait PolicyCopyContext: 'static + Send {
     type VM: VMBinding;

src/scheduler/gc_work.rs

@@ -763,7 +763,7 @@ use crate::plan::Plan;
 use crate::plan::PlanTraceObject;
 use crate::policy::gc_work::TraceKind;
 
-/// This provides an implementation of [`ProcessEdgesWork`](scheduler/gc_work/ProcessEdgesWork). A plan that implements
+/// This provides an implementation of [`crate::scheduler::gc_work::ProcessEdgesWork`]. A plan that implements
 /// `PlanTraceObject` can use this work packet for tracing objects.
 pub struct PlanProcessEdges<
     VM: VMBinding,

src/util/copy/mod.rs

@@ -24,7 +24,7 @@ const MAX_IMMIX_COPY_ALLOCATORS: usize = 2;
 type CopySpaceMapping<VM> = Vec<(CopySelector, &'static dyn Space<VM>)>;
 
 /// A configuration for GCWorkerCopyContext.
-/// Similar to [MutatorConfig](plan/mutator_context/struct.MutatorConfig.html),
+/// Similar to a `MutatorConfig`,
 /// We expect each copying plan to provide a CopyConfig.
 pub struct CopyConfig<VM: VMBinding> {
     /// Mapping CopySemantics to the actual copying allocators (CopySelector)