Add documentation checker for exported symbols

[clnl] / src / main / transpile.lisp

diff --git a/src/main/transpile.lisp b/src/main/transpile.lisp
index e4ca36029d46608c0e3d5b4933f89b982c723ee8..b50b4cdad102286c38f82ec447efd63fcc133d50 100644 (file)
--- a/src/main/transpile.lisp
+++ b/src/main/transpile.lisp
@@ -1,18 +1,5 @@
 (in-package #:clnl-transpiler)
 
-; This is responsible for taking an ast and turning it into valid CL code
-; targeting the nvm.  Here is where start to care about commands versus reporters
-; and ensuring that things are in the right place.  The reason we wait until here
-; is because we want to allow someone else to play with the AST before handing it off
-; to us.  For instance, the command center wants to add "show" to reporters, and
-; the users dictate based on entry point whether they are expecting a command
-; or a reporter.  So monitors can say "hey, transpile this reporter" and we'll check
-; to make sure it actually is.
-
-; Furthermore, the lisp code that any netlogo code would be transpiled to should
-; use exported symbols, such that anyone writing NetLogo code in lisp could use
-; the nvm in the same way that comes out of this transpiler
-
 (defparameter *prims* nil)
 
 (defun prim-name (prim) (getf prim :name))
@@ -24,8 +11,23 @@
 (defun find-prim (symb) (find symb *prims* :key #'prim-name))
 
 ; Let this grow, slowly but surely, eventually taking on calling context, etc.
-; For now, it's just a 
+; For now, it's just a
 (defun transpile-commands (parsed-ast)
+ "TRANSPILE-COMMANDS PARSED-AST => AST
+
+ARGUMENTS AND VALUES:
+
+  PARSED-AST: An ast as returned by the parser
+  AST: An common lisp AST that can be actually run in a common lisp instance
+
+DESCRIPTION:
+
+  TRANSPILE-COMMANDS takes a unambigious PARSED-AST and converts it to
+  Common Lisp code.
+
+  Calling eval on that code should work correctly as long as you have a
+  running engine.  This is the entry point for commands, so it does
+  extra checking to ensure that commands are actually in the PARSED-AST."
  `(progn
    ,@(mapcar #'transpile-command parsed-ast)))
 
@@ -37,6 +39,23 @@
   (t `(,(prim-func (find-prim (car command))) ,@(mapcar #'transpile-reporter (cdr command))))))
 
 (defun transpile-reporter (reporter)
+ "TRANSPILE-REPORTER REPORTER => AST
+
+ARGUMENTS AND VALUES:
+
+  REPORTER: An ast returned from the parser.
+  AST: An common lisp AST that can be actually run in a common lisp instance
+
+DESCRIPTION:
+
+  TRANSPILE-REPORTER takes a unambigious PARSED-AST and converts it to
+  Common Lisp code.
+
+  Calling eval on that code should work correctly as long as you have a
+  running engine.  This is the entry point for reporters, so it does
+  extra checking to ensure that the reporter is actually in the REPORTER.
+
+  The Common lisp code that is returned, when run, will return some value."
  (cond
   ((numberp reporter) reporter) ; The parser converts to double for us
   ((symbolp reporter) reporter) ; The parser should have checked that having a symbol here is ok