---
title: Cours de programmation séquentielle
subtitle: Commentaires
author: Orestis Malaspinas
sansfont: Sans Serif
---

# 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 `//`{.rust}.
- Les commentaires sur plusieurs lignes se commentent avec `/* ... */`{.rust}.

	<pre><code data-trim="hljs rust" class="lang-rust">
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.
}
	</code></pre>

## Commentaires de documentation (1/4)

- La commande `cargo doc --open`{.sh} génère la documentation en HTML.
- Les lignes de la documentation doivent commencer avec `///`{.rust}.
- Supporte le Markdown pour le formatage du texte :

	<pre><code data-trim="hljs rust">
/// 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
}
	</code></pre>

- Le code ci-dessus produit:
	
	![](figs/rust_doc.png){width=100%}

## Commentaires de documentation (2/4)

- Les parties entre triples guillemets sont des exemples d'utilisation (très pratique).
- Cela a la forme suivante:
	
	![](figs/doc_fun.png){width=100%}

## Commentaires de documentation (3/4)

- La documentation peut être utilisée comme test unitaire: `cargo test`{.sh}.
- Les parties entre triples accents graves sont compilées et exécutées comme tests.

	<pre><code data-trim="hljs rust">
/// 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
}
	</code></pre>

- La sortie est de la forme:

	<pre><code data-trim="hljs sh">
$ 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
	</code></pre>

- 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 `//!`{.rust} en début de ligne.

	<pre><code data-trim="hljs rust">
//! # Hello world\
//! \
//! `hello_world` est l'exemple typique de tout\
//! cours d'algorithmique.\
\
\
/// Cette fonction ajoute deux, puis multiplie par trois.
	</code></pre>

- Le code ci-dessus produit:
	
	![](figs/rust_doc_crate.png){width=100%}