Documentation

Another very important aspect of a software is documentation. It is useful to describe how to use a project, giving some examples and detailing the complete public API: let's see how we can document a crate in Rust.

Documenting a crate

Documentation is written in comments, but these doc-comments start with a special symbol. We use the token /// to document the item following the comment, and //! to document the item from within this item. Let's start by seeing an example of the latter.

At the top of our crate's root (specifically, in the file main.rs), we'll add the following comment:

//! An FTP server, written using tokio and futures-await.

Here, we use the //! form because we cannot write a comment before a crate; we can only write a comment from within the crate.

Documenting a module

Documenting a module is very similar: we add a comment of the form //! at the top of a module's file. Let's add the following doc-comment in codec.rs:

//! FTP codecs to encode and decode FTP commands...