Merge branch 'documentation'

Author: sourrust

README.md

@@ -1,10 +1,11 @@
 # Laço
 
-A better REPL for lua. This was mainly for luajit because the default
-interactive mode, ie. the REPL, was pretty bad. You couldn't move back
-and forth in the to edit, and no going through history. With laco you
-can actually do that, and I also believe that that regular lua can as
-well.
+A better REPL for lua. This was created mainly for luajit because the
+default interactive mode, better known as the REPL, was pretty bare
+bones. You can't move left or right in the current line if wanted to
+edit the line, and there is no history for repeating commands easily.
+With laco you can actually do that, and I also believe that that regular
+lua REPL can as well.
 
 ## Features
 
@@ -20,20 +21,20 @@ well.
 ```
 
 * In memory history, so pressing up will go to the previous line.
+* Command mode (use `:help` to see the list of commands)
 
 This is still in early development so there isn't much so far, but I
 think its enough to use a replacement (atleast for luajit users).
 
 ## Laço?
 
-In Portuguese, laco mean loop and since Lua is a Portuguese name and a
+In Portuguese, laco mean loop. Since Lua is a Portuguese name, and a
 REPL is a read eval print loop, the name was born.
 
 ## Building
 
-Since laco depends on [linenoise](https://github.com/antirez/linenoise#tested-with),
-I don't think this will work for Windows terminals, but nevertheless,
-here are the step on building.
+Since laco depends on [linenoise][1], I don't think this will work for
+Windows terminals, but nevertheless, here are the step on building.
 
 **Denpendencies (not included):**
 
@@ -43,7 +44,7 @@ here are the step on building.
 **Note**: This is for regular lua, to enable luajit you need to replace.
 `cmake ..` with `cmake -DLACO_USE_LUAJIT=on ..`. Also if you are using
 anything lua 5.2+, I'm not sure if this will work since I've only tested
-on luajit which is currently 5.1
+on luajit which is currently 5.1.
 
 ```bash
 git clone --recursive https://github.com/sourrust/laco.git
@@ -55,3 +56,5 @@ make
 ```
 
 The binary will be located in `build/bin` and it can be run from there.
+
+[1]: https://github.com/antirez/linenoise#tested-with

src/commands.h

@@ -3,6 +3,10 @@
 
 struct LacoState;
 
+/**
+ * Gets passed ever line to see if it matches one of the REPL command. If it
+ * does, that command will be executed.
+ */
 void handle_command(struct LacoState* laco, char* line);
 
 #endif /* LACO_COMMANDS_H */

src/flags.h

@@ -4,10 +4,8 @@
 struct LacoState;
 
 /**
- * Takes the arguments inside of LacoState and executed a flags
- * functionality
- *
- * param          pointer to LacoState
+ * Takes the arguments inside of LacoState and executed any of flags
+ * functionality when the arguments match.
  */
 void laco_handle_flag(struct LacoState* laco);
 

src/laco.h

@@ -7,66 +7,39 @@ struct lua_State;
 typedef struct LacoState LacoState;
 
 /**
- * Makes a new LacoState.
- *
- * param          argument count
- * param          arguments
- *
- * return a pointer to new LacoState.
+ * Allocates and initializes a new state for the laco REPL.
  */
 LacoState* laco_new_laco_state(int argc, const char** argv);
 
 /**
- * Destroys the internal variable, but doesn't try to free the LacoState
- * pointer itself.
- *
- * param          pointer to LacoState
- *
- * return 1 if pointer isn't NULL
+ * Cleans up all allocted data internally along with the pointer to laco
+ * state. If the pointer isn't NULL, the function returns 1.
  */
 int laco_destroy_laco_state(LacoState* laco);
 
 /**
- * Gets the lua state held with laco.
- *
- * param          pointer to LacoState
- *
- * return a pointer to lua_State
+ * Gets the lua state held within laco.
  */
 struct lua_State* laco_get_laco_lua_state(LacoState* laco);
 
 /**
- * Gets the laco version held with laco.
- *
- * param          pointer to LacoState
- *
- * return a string of characters representing laco's version number
+ * Gets the laco version held with laco. The format for the version is
+ * `major.minor.patch`, essentually semver format.
  */
 const char* laco_get_laco_version(LacoState* laco);
 
 /**
- * Gets the arraying of arguments passed to laco.
- *
- * param          pointer to LacoState
- *
- * return an array of characters string passes into laco
+ * Gets the arraying of arguments passed to the laco executable.
  */
 const char** laco_get_laco_args(LacoState* laco);
 
 /**
- * Get the current status of the laco repl.
- *
- * param          pointer to LacoState
- *
- * return the current status of laco
+ * Gets the current status of the laco REPL.
  */
 int laco_get_laco_status(LacoState* laco);
 
 /**
- * Set the current status of laco.
- *
- * param          pointer to LacoState
- * param          status to be set
+ * Sets the current status of the laco REPL.
  */
 void laco_set_laco_status(LacoState* laco, int status);
 

src/util.h

@@ -4,49 +4,38 @@
 struct LacoState;
 
 /**
- * Load a line into the lua stack to be evaluated later
- *
- * param          pointer to LacoState
- *
- * return -1 if there is no line input to load
+ * Load a line into the lua stack to evaluated later. This function will
+ * return -1 if there is no line input to load.
  */
 int laco_load_line(struct LacoState* laco);
 
 /**
- * Called after laco_load_line, this evaluated the line as a function and
- * hands of the result for printing
- *
- * param          pointer to LacoState
+ * Called after laco_load_line, this will evalute the line as a function and
+ * hands off the result for printing.
  */
 void laco_handle_line(struct LacoState* laco);
 
 /**
- * Kills the loop with exiting message if specified
- *
- * param          pointer to LacoState
- * param          exit with status
- * param          error message
+ * Kills the loop with exiting message if specified.
  */
 void laco_kill(struct LacoState* laco, int status, const char* message);
 
 /**
- * When there is a value on the lua stack, it will print out depending on
- * the type it is
- *
- * param          pointer to LacoState
- *
- * return LUA_ERRSYNTAX if the value has some error
+ * When there is a value on the lua stack, this will print out the current
+ * type it is. When an error accures, laco_print_type will return
+ * LUA_ERRSYNTAX.
  */
 int laco_print_type(struct LacoState* laco);
 
 /**
- * Prints out and pops off errors pushed into the lua stack
- *
- * param          pointer to LacoState
- * param          incoming lua stack status
+ * Prints out and pops off errors pushed into the lua stack.
  */
 void laco_report_error(struct LacoState* laco, int status);
 
+/**
+ * Checks if the test string matches any of the string in matches and
+ * returns 1 if true, and 0 if false.
+ */
 int laco_is_match(const char** matches, const char* test_string);
 
 #endif /* LACO_UTIL_H */