From 9067a9d6610dc40d360cf177643750acfc99481a Mon Sep 17 00:00:00 2001 From: Carlos Bilbao Date: Tue, 24 Oct 2023 08:26:25 -0500 Subject: [PATCH] docs: Add documentation style guidelines and Documentation/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation style guidelines within CONTRIBUTING.md to help clarify our expectations from a documentation standpoint. Place it in a new directory Documentation/. Co-developed-by: Carlos López Signed-off-by: Carlos López Signed-off-by: Carlos Bilbao --- CONTRIBUTING.md | 3 + Documentation/DOC-GUIDELINES.md | 129 ++++++++++++++++++++++++++++++++ README.md | 1 + 3 files changed, 133 insertions(+) create mode 100644 Documentation/DOC-GUIDELINES.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 760af1f95..33e45fd4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,3 +48,6 @@ before allowing them to be committed. It can be installed by running ``` from the projects root directory. + +For detailed instructions on documentation guidelines please have a look at +[DOC-GUIDELINES.md](Documentation/DOC-GUIDELINES.md). diff --git a/Documentation/DOC-GUIDELINES.md b/Documentation/DOC-GUIDELINES.md new file mode 100644 index 000000000..fad43253e --- /dev/null +++ b/Documentation/DOC-GUIDELINES.md @@ -0,0 +1,129 @@ +Documentation Style +=================== + +In this project, code documentation is generated using Rustdoc, which +automatically generates interactive web documentation. Here are some +guidelines for documenting code effectively: + +- Follow [Rust's official indications.](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html) + +- Follow standard Markdown format, e.g. variables between backticks: + +- When adding doc comments to your code, use triple slashes (`///`) + to document items; if you also want to document modules or crates, use + `//!` and `#[doc = ""]` for documenting fields or expressions. + +```rust +/// This function does A, takes parameter of type `m` +/// It returns B, keep in mind C +fn main(a: m) { + // Some code here +} + +``` + +- Documenting trait implementations is optional since the generated + Rust core library already documents them. The exception would be if your + implementation does something counterintuitive to the trait's general + definition. + +- When mentioning a type (e.g. \`RWLock\`, \`WriteLockGuard\`) it's good to + add a link to the type with square brackets (e.g. [\`RWLock\`], + [\`WriteLockGuard\`]). + +- When documenting a function, examples of usage relying on code blocks + can help understand how to use your code. However, keep in mind that + said code will be built and ran during tests, so it also needs to be + maintained -- keep it simple. Here is an example of function + documentation with Arguments, Returns and Examples: + +```rust + +/// Compares two [`Elf64AddrRange`] instances for partial ordering. It returns +/// [`Some`] if there is a partial order, and [`None`] if there is no +/// order (i.e., if the ranges overlap without being equal). +/// +/// # Arguments +/// +/// * `other` - The other [`Elf64AddrRange`] to compare to. +/// +/// # Returns +/// +/// - [`Some`] if [`self`] is less than `other`. +/// - [`Some`] if [`self`] is greater than `other`. +/// - [`Some`] if [`self`] is equal to `other`. +/// - [`None`] if there is no partial order (i.e., ranges overlap but are not equal). +/// +/// # Examples +/// +/// ```rust +/// use svsm::elf::Elf64AddrRange; +/// use core::cmp::Ordering; +/// +/// let range1 = Elf64AddrRange { vaddr_begin: 0x1000, vaddr_end: 0x1100 }; +/// let range2 = Elf64AddrRange { vaddr_begin: 0x1100, vaddr_end: 0x1200 }; +/// +/// assert_eq!(range1.partial_cmp(&range2), Some(Ordering::Less)); +/// ``` +impl cmp::PartialOrd for Elf64AddrRange { + fn partial_cmp(&self, other: &Elf64AddrRange) -> Option { + //(...) +``` + +- Add section "Safety" if necessary to clarify what is unsafe, specially in + public (`pub`) interfaces, when using `unsafe` blocks or in cases where + undefined behavior may arise. For example: + +```rust +/// # Safety +/// +/// This function is marked as `unsafe` because it uses unsafe assembly. +/// It is the responsibility of the caller to ensure the following: +/// +/// 1. The pointer `data` must be valid and properly allocated memory. +/// 2. The length `len` must accurately represent the number of elements in +/// `data`. +/// 3. The caller must also ensure that the memory is correctly initialized +/// +pub unsafe fn example_memcpy(dest: *mut T, src: *const T, len: usize) { + // Ensure the pointers are not null + assert!(!dest.is_null() && !src.is_null()); + let mut rcx: usize; + + unsafe { + asm!( + "rep movsb" + : "={rcx}"(rcx) + : "0"(len), "D"(dest), "S"(src) + : "memory" + ); + } +} +``` +- We can't have a section "Panic" for every place the SVSM may panic, but + they should be included if your code checks assertions or uses the + `unwrap()` method. For instance: + +```rust +/// # Panics +/// +/// This function does not panic under normal circumstances. However, if +/// the length `len` is greater than the allocated memory's actual capacity, +/// it will panic. +/// +pub fn my_function(buffer: &mut Vec, len: usize) { + if len > buffer.capacity() { + panic!("Length exceeds allocated capacity!"); + } +``` + +- Remember that if you update code, you also have to update its related + documentation to ensure maintainability. + +- Be aware that your documentation comments have the potential to break the + documentation generation process (cargo doc), which can delay the merging + of your changes. Your new documentation should be warning-free. + +In general, even imperfect documentation is better than none at all. +Prioritize documenting functions that are publicly exported, especially +API calls, over internal helper functions. diff --git a/README.md b/README.md index 1de316c26..79a516758 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ Contributing Contributing to the project is as easy as sending a pull-request via GitHub. For detailed instructions on patch formatting and contribution guidelines please have a look at [CONTRIBUTING.md](CONTRIBUTING.md). +For documentation guidelines consult [DOC-GUIDELINES.md](Documentation/DOC-GUIDELINES.md). TODO List ---------