Rust – il linguaggio – 47

florence

Proseguendo da qui oggi eccomi qui: /usr/local/share/doc/rust/html/book/documentation.html.

Documentazione

Documentation is an important part of any software project, and it’s first-class in Rust. Let’s talk about the tooling Rust gives you to document your project. Vero 😀 io ultimamente considero solo le cose ben documentate (e aggiornate), meglio se senza bugs.

rustdoc

The Rust distribution includes a tool, rustdoc, that generates documentation. rustdoc is also used by Cargo through cargo doc.
Documentation can be generated in two ways: from source code, and from standalone Markdown files.

Documentare il codice sorgente

The primary way of documenting a Rust project is through annotating the source code. You can use documentation comments for this purpose:

/// Constructs a new `Rc`.
///
/// # Examples
///
/// ```
/// use std::rc::Rc;
///
/// let five = Rc::new(5);
/// ```
pub fn new(value: T) -> Rc {
    // implementation goes here
}

Produce un file .html come quelli che sto esaminando, anzi uno di quelli proprio 😀

The first thing to notice about this annotation is that it uses /// instead of //. The triple slash indicates a documentation comment.

Documentation comments are written in Markdown.

Rust keeps track of these comments, and uses them when generating documentation. This is important when documenting things like enums:

/// The `Option` type. See [the module level documentation](index.html) for more.
enum Option {
    /// No value
    None,
    /// Some value `T`
    Some(T),

The above works, but this does not:

/// The `Option` type. See [the module level documentation](index.html) for more.
enum Option {
    None, /// No value
    Some(T), /// Some value `T`
}

You’ll get an error:

hello.rs:4:1: 4:2 error: expected ident, found `}`
hello.rs:4 }
           ^

This unfortunate error is correct: documentation comments apply to the thing after them, and there’s nothing after that last comment.

Seguono una serie di consigli che non riporto, anche se impo, nèh! 😀
Come pure non riporto come produrre la documentazione con rustdoc o cargo test.

Documentare i moduli

Rust has another kind of doc comment, //!. This comment doesn’t document the next item, but the enclosing item. In other words:

mod foo {
    //! This is documentation for the `foo` module.
    //!
    //! # Examples

    // ...

This is where you’ll see //! used most often: for module documentation. If you have a module in foo.rs, you’ll often open its code and see this:

//! A module for using `foo`s.
//!
//! The `foo` module contains a lot of useful functionality blah blah blah

Check out RFC 505 for full conventions around the style and format of documentation.

Altre documentazioni

All of this behavior works in non-Rust source files too. Because comments are written in Markdown, they’re often .md files.

When you write documentation in Markdown files, you don’t need to prefix the documentation with comments. For example:

/// # Examples
///
/// ```
/// use std::rc::Rc;
///
/// let five = Rc::new(5);
/// ```

Seguono poi tutta una serie di dritte, troppo specifiche per il mio esame, tanto sono di là 😀
In conclusione: i tools per produrre documentazione con Rust rockzs! 😀

:mrgreen:

Posta un commento o usa questo indirizzo per il trackback.

Trackback

Rispondi

Inserisci i tuoi dati qui sotto o clicca su un'icona per effettuare l'accesso:

Logo di WordPress.com

Stai commentando usando il tuo account WordPress.com. Chiudi sessione /  Modifica )

Google photo

Stai commentando usando il tuo account Google. Chiudi sessione /  Modifica )

Foto Twitter

Stai commentando usando il tuo account Twitter. Chiudi sessione /  Modifica )

Foto di Facebook

Stai commentando usando il tuo account Facebook. Chiudi sessione /  Modifica )

Connessione a %s...

Questo sito utilizza Akismet per ridurre lo spam. Scopri come vengono elaborati i dati derivati dai commenti.

%d blogger hanno fatto clic su Mi Piace per questo: