Use Rust-style doc comments

[wks]

The Rust MMTk is ported from JikesRVM, a Java project. We still have some functions using JavaDoc-style comments, like this one:

    /**
     * Commit pages to the page budget.  This is called after
     * successfully determining that the request can be satisfied by
     * both the page budget and virtual memory.  This simply accounts
     * for the discrepancy between <code>committed</code> and
     * <code>reserved</code> while the request was pending.
     *
     * This *MUST* be called by each PageResource during the
     * allocPages, and the caller must hold the lock.
     */
    fn commit_pages(&self, reserved_pages: usize, actual_pages: usize, tls: VMThread) {

In Rust, doc comments can be line comments with three slashes ///, or block comments starting with exactly two asterisks /** */ (therefore neither /* */ nor /*** */ are treated as doc comments).

Rust comments use MarkDown format, so we can write `committed` instead of <code>committed</code>.

Asterisks in the beginning of each line will be interpreted as unordered lists in MarkDown, i.e.

• Commit pages ...
• successfully determining ...
• both the ...

We should go through the mmtk-core code base and update the comments so that they use the proper Rust-style doc comments.

References

• Rust Reference: https://doc.rust-lang.org/reference/comments.html
• Rust By Example: https://doc.rust-lang.org/rust-by-example/meta/doc.html

Related issues

• Issue Cleanup PageResource and {FreeList,Monotone}PageResource #617 also mentioned JavaDoc-style comments in some parts of mmtk-core.