From 17ce8c98d86b6217fa2d18035e003c375da01902 Mon Sep 17 00:00:00 2001
From: Daniel Kochmanski <daniel@turtleware.eu>
Date: Fri, 6 Apr 2018 11:03:14 +0200
Subject: [PATCH] cosmetic: add some barebones comments and docs for bytecmp

---
 src/c/compiler.d                              |  2 +-
 src/c/interpreter.d                           |  4 +-
 src/doc/new-doc/developer-guide/bytecodes.txi | 44 +++++++++++++++++++
 3 files changed, 47 insertions(+), 3 deletions(-)
 create mode 100644 src/doc/new-doc/developer-guide/bytecodes.txi

diff --git a/src/c/compiler.d b/src/c/compiler.d
index f74969887..7f4b9ecc1 100644
--- a/src/c/compiler.d
+++ b/src/c/compiler.d
@@ -1421,7 +1421,7 @@ c_function(cl_env_ptr env, cl_object args, int flags) {
   return asm_function(env, function, flags);
 }
 
-static int
+static int                      /* XXX: here we look for function in cmpenv */
 asm_function(cl_env_ptr env, cl_object function, int flags) {
   if (!Null(si_valid_function_name_p(function))) {
     cl_object ndx = c_tag_ref(env, function, @':function');
diff --git a/src/c/interpreter.d b/src/c/interpreter.d
index 74f510584..2baeaf86b 100644
--- a/src/c/interpreter.d
+++ b/src/c/interpreter.d
@@ -712,7 +712,7 @@ ecl_interpret(cl_object frame, cl_object env, cl_object bytecodes)
        Calls the local or global function with N arguments
        which have been deposited in the stack.
     */
-    CASE(OP_LFUNCTION); {
+    CASE(OP_LFUNCTION); {       /* XXX: local function (fix comment) */
       int lex_env_index;
       GET_OPARG(lex_env_index, vector);
       reg0 = ecl_lex_env_get_fun(lex_env, lex_env_index);
@@ -724,7 +724,7 @@ ecl_interpret(cl_object frame, cl_object env, cl_object bytecodes)
        may be defined in the global environment or in the local
        environment. This last value takes precedence.
     */
-    CASE(OP_FUNCTION); {
+    CASE(OP_FUNCTION); {        /* XXX: global function (fix comment) */
       GET_DATA(reg0, vector, data);
       reg0 = ecl_fdefinition(reg0);
       THREAD_NEXT;
diff --git a/src/doc/new-doc/developer-guide/bytecodes.txi b/src/doc/new-doc/developer-guide/bytecodes.txi
new file mode 100644
index 000000000..5c8b12ce5
--- /dev/null
+++ b/src/doc/new-doc/developer-guide/bytecodes.txi
@@ -0,0 +1,44 @@
+@node Bytecodes
+@section Bytecodes
+
+Bytecodes compiler and interpreter are integral part of ECL
+system. Call to @code{eval} invokes the bytecode compiler and then the
+bytecode interpreter.
+
+@itemize
+@item @code{src/c/compiler.d} - bytecode compiler 
+@item @code{src/c/interpreter.d} - bytecode interpreter
+@item @code{src/c/interpreter.d} - bytecode disassembler
+@end itemize
+
+Structure @code{ecl_bytecodes} has the following fields:
+
+@itemize
+@item @code{name}          - function name
+@item @code{definition}    - function definition in list form
+@item @code{entry}         - entry address (function @code{_ecl_bytecodes_dispatch_vararg})
+@item @code{code_size}     - number of bytecodes
+@item @code{code}          - stores actual bytecode
+@item @code{data}          - non-immediate constants used in the code
+@item @code{file}          - file where it was defined
+@item @code{file_position} - position in file where function was created
+@end itemize
+
+Moreover if bytecompiled function is a closure then its structure is
+@code{ecl_bclosure}:
+
+@itemize
+@item @code{code}  - closure function (@code{ecl_bytecodes})
+@item @code{lex}   - closure lexical environment
+@item @code{entry} - closure entry address (function _ecl_bclosure_dispatch_vararg)
+@end itemize
+
+@subsection Bytecode compiler
+
+@subsection Bytecode interpreter
+
+@subsection Bytecode disassembler
+
+@defun{si:bc-split} {@var{funciton}}
+Returns five values: lex, bytecodes, data and name.
+@end defun