WIP: Update basics.md sintax and rework comments.md

basics/basics.md

@@ -8,7 +8,7 @@ Dans cette section nous allons aborder les bases du langage pour écrire nos pro
 
 # Objectif  
 
-Nous allons apprendre la [syntaxe](https://en.wikipedia.org/wiki/Java_syntax) de programmation Java et les bases communes à tous les langages de programmation.
+Nous allons apprendre la [syntaxe](https://en.wikipedia.org/wiki/Java_syntax) de Java et les bases communes à tous les langages de programmation.
 
 * [Commentaires](comments.md)
 * [Variables](variables/variables.md)

basics/comments.md

@@ -1,20 +1,21 @@
 # Les commentaires  
 
-Les commentaires sont des lignes dans notre code qui vont être ignorée lors de la compilation et l'éxecution du programmes.  
-Ils nous permettent d'expliquer des parties de codes compliqués. Ils ont utiles pour nous et les autres développeurs.
+Les commentaires sont des lignes dans notre code qui vont être ignorées lors de la compilation et l'exécution du programme.  
+Ils nous permettent d'expliquer des parties de codes compliquées. Ils sont utiles voir indispensables dès lors que l'on travaille en équipe, afin de faciliter la compréhension du code.
 
 #### Regular comments
 
-Il existe deux types de commentaires dits « **réguliers** » :  
+Il existe deux types de commentaires dits *réguliers* :  
 {% method -%}
-Des **Single-line** :  
+**Sur une ligne** :  
 {% sample lang="java" -%}
 ```
 // Ce commentaire ne couvre qu'une ligne et ignore tout ce qui se trouve jusqu'au prochain retour à la ligne.
 ```  
 {% endmethod %}
+
 {% method -%}
-#### Des blocs de commentaires :  
+**Sur plusieurs lignes** :  
 {% sample lang="java" -%}
 ```
 /* Ce commentaire couvre tout ce qui
@@ -23,10 +24,9 @@ Des **Single-line** :
 {% endmethod %}
 
 
-#### La javadocs  
+#### La javadoc  
 {% method -%}
-Un certain type de blocs de commentaires sont utilisés pour créer la **javadocs**. Pour faire simple, il s'agit de créer des pages html expliquant comment le code fonctionne. Nous reverrons cela plus tard.
-En voici un exemple :  
+La javadoc sert directement à la compréhension du code, que ce soit via l'inspection au sein d'un IDE, ou alors via un site web. Celui ci est généré à partir des sources d'un projet. La javadoc est un bloc spécifique de commentaires, que l'on initie avec deux **.En voici un exemple :  
 {% sample lang="java" -%}
 ```java
 /**
@@ -43,13 +43,20 @@ public static void main(String[] args) {
 
 # Utiliser les commentaires
 {% method -%}
-Les commentaires s'utilisent n'importe où dans le code. Vous pouvez réaliser des choses comme cecis :  
+Les commentaires s'utilisent n'importe où dans le code :  
 {% sample lang="java" -%}
 ```java
+package foo;
+
+/*
+ * Ce commentaire est généralement appelé "header" du fichier.
+ */
 public class HelloWorld {
 
+    /**
+     * Affiche seulement "Hello World!" dans la console, car "Hi there!" est commenté.
+     */
     public static void main(String[] args) {
-        // Permet d'afficher Hello World ! dans la console et de ne pas éxecuter Hi there !.
         System.out.println("Hello World !");
         // System.out.println("Hi there !");