Docstrings, ortographe, explications, ... Les trucs chiantos. N'hésitez pas à corriger mes erreurs de style.

environnement.lisp

@@ -1,57 +1,90 @@
-;; gestion de l'environnement
+;; Gestion de l'environnement
+
+;; Attention :
+;;  - Lorsqu'on fait un setf, ça renvoie la valeur affectée, pas
+;;    l'objet modifié. Si on veut le renvoyer, il faut explicitement
+;;    le mettre après le setf.
+;;  - Les environnements sont partagés entre toutes les clôtures et
+;;    autres qui les utilisent. Par ex. :
+;;      (let ((x 0))
+;;         (lambda () (setf (x) (+ x 1)))
+;;         (lambda () x))
+;;    Dans ce cas, les deux lambdas ont accès au même x, dans le même
+;;    environnement. La modification par l'une des fonctions se
+;;    répercute sur la valeur accédée par l'autre.
+;;  - Lorsqu'on définit une fonction, il faut mettre juste après la
+;;    liste des paramètres une chaîne de caractères qui documente la
+;;    fonction (une docstring).
+
+
+;; Exemple de la structure env-stack après création de deux
+;; environnements en plus du top-level et ajout de plusieurs laisons.
 (defvar exemple-env-stack 
-  '(((x . plop)) ;; Environnement le plus bas. (derriere definition)
-    ((y . "#lambda") 
+  '(;; Environnement le plus bas (dernières définitions par ordre
+    ;; chronologique).
+    ((x . plop))
+    ;; Un autre environnement (définitions "plus vieilles").
+    ((y . "#lambda")
      (x . "bijour")
      (z . 123))
+    ;; Top-level. Environnement le plus haut (définitions "globales"
+    ;; faites avec defun, defvar etc.).
     ((y . 56)
      (x . 42)
-     (foo . "#lambda")))) ;; Top-level. Environnement le plus haut (premiere definition)
+     (foo . "#lambda"))))
 
 ;; '((...) (...) (...)) => 3 environnement dans env-stack
 
-(defun empty-env-stack () '(())) ;; Constructeur de la pile d'environnement
+(defun empty-env-stack ()
+  "Constructeur de la pile d'environnements."
+  '(()))
 
-(defun push-new-env (env-stack) ;; env-stack en parametre = toute la pile.
+(defun push-new-env (env-stack)
+  "Crée un nouvel environnement, l'ajoute à ENV-STACK et renvoie la
+version modifiée (sans altérer l'original).
+Le paramètre ENV-STACK est toute la pile d'environnements."
   (cons '() env-stack))
 
-(defun add-binding (env-stack name value) ;; ajoute une definition
+(defun add-binding (env-stack name value)
+  "Ajoute une liaison au dernier environnement (le plus bas)."
   (setf (car env-stack)
 	(cons (cons name value)
 	      (car env-stack)))
-  env-stack
-  )
+  env-stack)
 
-(defun set-binding (env-stack name new-value) ;; modifie une definition
+(defun set-binding (env-stack name new-value)
+  "Modifie la valeur associée à une liaison."
   (setf (cdr (get-binging name))
 	new-value)
-  env-stack
-  )
+  env-stack)
 
-(defun get-binding-value (env-stack name) ;; recupere la valeur associer a name
+(defun get-binding-value (env-stack name)
+  "Récupère la valeur associée a NAME ."
   (cdr (get-binding name)))
 
-(defun get-binding (env-stack name) ;; recupere l'association correspondant a name
+(defun get-binding (env-stack name)
+  "Récupère la liaison correspondant à NAME ."
   (if (atom env-stack)
-      nil ;; TODO : Penser a peut etre mettre un warn ou error
+      nil ; TODO : Penser à peut-être mettre un warn ou error.
   (let ((ass (assoc name (car env-stack))))
     (if ass ass
-      (get-binding (cdr env-stack) name))))
-  )
+      (get-binding (cdr env-stack) name)))))
 
-(defun top-level (env-stack) ;; Recupere la pile d'environnement contenant unique l'environnement top-level
+(defun top-level (env-stack)
+  "Recupere la pile d'environnement contenant uniquement
+l'environnement top-level"
   (if (atom (cdr env-stack))
       env-stack
-    (top-level (cdr env-stack)))
-)
+    (top-level (cdr env-stack))))
 
-(defun add-top-level-binding (env-stack name value) ;; ajoute une definition
-  (add-binding (top-level env-stack) name value)
-  )
+(defun add-top-level-binding (env-stack name value)
+  "Ajoute une liaison \"globale\" à l'environnement top-level."
+  (add-binding (top-level env-stack) name value))
 
 (defun set-top-level-binding (env-stack name new-value) ;; modifie une definition
-  (set-binding (top-level env-stack) name new-value)
-  )
+  "Modifie la valeur associée à une liaison \"globale\" de
+l'environnement top-level."
+  (set-binding (top-level env-stack) name new-value))
 
 (defun test-env (num)
   (case num
@@ -61,4 +94,4 @@
 	(3 (add-binding (add-binding (push-new-env (empty-env-stack)) 'x 42) 'y 56))
 	))
 
-(test-env 0)
+(test-env 0)