Cours de programmation séquentielle

Commentaires

Orestis Malaspinas

Commentaires

Commentaires simples

  • La meilleure façon de commenter son code est de bien nommer variables/fonctions.
  • En rust les commentaires simples viennent après les //.

  • Les commentaires sur plusieurs lignes se commentent avec /* ... */.

    
fn main() { 
  // Tout programme Rust a un point d'entrée qui est
  // une fonction fn main().

  /* 
  On peut également documenter sur plusieurs lignes. 
  Cela se fait comme ceci.
  */ 

  println!("Hello, World!"); // Ceci est un macro en ligne.
}

Commentaires de documentation (1/4)

  • La commande cargo doc --open génère la documentation en HTML.
  • Les lignes de la documentation doivent commencer avec ///.

  • Supporte le Markdown pour le formatage du texte :

    
/// Cette fonction ajoute deux, puis multiplie par trois.
///
/// # Exemple
///
/// ```
/// let five = 5;
///
/// add_two_mul_three(five);
/// ```
pub fn add_two_mul_three(x: i32) -> i32 {
  // ajoutons deux et multiplions par trois
  (x + 2) * 3
}

  • Le code ci-dessus produit:

Commentaires de documentation (2/4)

  • Les parties entre triples guillemets sont des exemples d’utilisation (très pratique).

  • Cela a la forme suivante:

Commentaires de documentation (3/4)

  • La documentation peut être utilisée comme test unitaire: cargo test.

  • Les parties entre triples accents graves sont compilées et exécutées comme tests.

    
/// Cette fonction ajoute deux, puis multiplie par trois.
///
/// # Exemple
///
/// ```
/// use tests::add_two_mul_three;
/// let five = 5;
/// add_two_mul_three(five);
/// ```
pub fn add_two_mul_three(x: i32) -> i32 {
  (x + 2) * 3
}

  • La sortie est de la forme:

    
$ cargo test --doc
  Finished dev [unoptimized + debuginfo] target(s) in 0.01s
 Doc-tests hello_world
running 1 test
test src/lib.rs - add_two_mul_three (line 11) ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

  • Cela permet également de s’assurer que les exemples sont toujours valides!

Commentaires de documentation (4/4)

  • La documentation du projet en entier se fait avec //! en début de ligne.

    
//! # Hello world\
//! \
//! `hello_world` est l'exemple typique de tout\
//! cours d'algorithmique.\
\
\
/// Cette fonction ajoute deux, puis multiplie par trois.

  • Le code ci-dessus produit: