Inner documentation attaches comments beginning with /// to the next Rust item. Use it to explain public structs, methods, and traits as part of a usable API, while //! documentation applies to the file’s outer scope. section 6.11.2
Use inner documentation to make library interfaces easier to understand:
- Describe what a LinkedList provides before its declaration. section 6.11.2
- Document methods such as new and append with behavior-focused descriptions. section 6.11.2
- Include links such as [`LinkedList<T>`] in rendered documentation. section 6.11.2
Documenting a linked-list API
/// Provides a singly linked list implementation with iterator access. pub struct LinkedList<T> { head: Option<ListItemPtr<T>>, } impl<T> LinkedList<T> { /// Constructs a new, empty [`LinkedList<T>`]. pub fn new() -> Self { /* ... */ } /// Appends an element to the end of the list. pub fn append(&mut self, t: T) { /* ... */ } } section 6.11.2
Listing 6.1 LinkedList with documentation
/// Provides a singly linked list implementation with iterator access.
pub struct LinkedList<T> {
head: Option<ListItemPtr<T>>,
}
impl<T> LinkedList<T> {
/// Constructs a new, empty [`LinkedList<T>`].
pub fn new() -> Self {
Self { head: None }
}
/// Appends an element to the end of the list. If the list is empty,
/// the element becomes the first element of the list.
pub fn append(&mut self, t: T) {
match &self.head {
Some(head) => {
let mut next = head.clone();
while next.as_ref().borrow().next.is_some() {
let n = next.as_ref().borrow()
.next.as_ref().unwrap().clone();
next = n;
}
next.as_ref().borrow_mut().next =
Some(Rc::new(RefCell::new(ListItem::new(t))));
}
None => {
self.head = Some(Rc::new(RefCell::new(ListItem::new(t))));
}
}
}
/// Returns an iterator over the list.
pub fn iter(&self) -> Iter<T> {
Iter {
next: self.head.clone(),
data: None,
phantom: PhantomData,
}
}
/// Returns an iterator over the list that allows mutation.
pub fn iter_mut(&mut self) -> IterMut<T> {
IterMut {
next: self.head.clone(),
data: None,
phantom: PhantomData,
}
}
/// Consumes this list returning an iterator over its values.
pub fn into_iter(self) -> IntoIter<T> {
IntoIter {
next: self.head.clone(),
}
}
}
Inspect the complete documented LinkedList declaration and its method comments. section 6.11.2
