Add first docs

Author: MaJerle

README.md

@@ -7,11 +7,13 @@ It targets communication with embedded systems from remote terminal to quickly s
 
 ## Features
 
-* Lightweight commands shell for embedded systems 
+* Lightweight commands shell for embedded systems
 * Platform independent and very easy to port
     * Development of library under Win32 platform
 * Written in C language (C99)
 * No dynamic allocation, maximum number of commands assigned at compile time
+* Highly configurable
+* Simple help-text with `cmd -v` option
 * User friendly MIT license
 
 ## Contribute

dev/VisualStudio/lwshell_dev.vcxproj

@@ -143,6 +143,7 @@
     </Link>
   </ItemDefinitionGroup>
   <ItemGroup>
+    <ClCompile Include="..\..\examples\example_minimal.c" />
     <ClCompile Include="..\..\lwshell\src\lwshell\lwshell.c" />
     <ClCompile Include="main.c" />
   </ItemGroup>

dev/VisualStudio/lwshell_dev.vcxproj.filters

@@ -19,5 +19,8 @@
     <ClCompile Include="..\..\lwshell\src\lwshell\lwshell.c">
       <Filter>Source Files\LWSHELL</Filter>
     </ClCompile>
+    <ClCompile Include="..\..\examples\example_minimal.c">
+      <Filter>Source Files</Filter>
+    </ClCompile>
   </ItemGroup>
 </Project>

dev/VisualStudio/main.c

@@ -3,6 +3,8 @@
 #include <string.h>
 #include <stdint.h>
 
+void    example_minimal(void);
+
 int32_t
 addint_cmd(int32_t argc, char** argv) {
     long long i1, i2;
@@ -68,17 +70,13 @@ shell_output(const char* str, lwshell_t* lw) {
     }
 }
 
+/* Program entry point */
 int
-main(int argc, char** argv) {
-    printf("Program started...\r\n");
-    printf("ARGC: %d\r\n", argc);
-    for (size_t i = 0; i < argc; ++i) {
-        printf("ARGV %d: %s\r\n", i, argv[i]);
-    }
-    printf("\r\n");
-
+main(void) {
     /* Init library */
     lwshell_init();
+
+    /* Add optional output function for the purpose of the feedback */
     lwshell_set_output_fn(shell_output);
 
     /* Define shell commands */
@@ -88,21 +86,11 @@ main(int argc, char** argv) {
     lwshell_register_cmd("subdbl", subdbl_cmd, "Substitute 2 double numbers and prints them");
 
     /* User input to process every character */
-    printf("Start entering your text and press enter...\r\n");
+    printf("Start entering your command and press enter...\r\n");
     while (1) {
         char c = getch();
-#if 0
-        if (c == '\b') {
-            printf("\b \b");
-        } else {
-            printf("%c", c);
-        }
-        if (c == '\r') {
-            printf("\n");
-        }
-#endif
 
-        /* Now insert input */
+        /* Insert input to library */
         lwshell_input(&c, 1);
     }
     return 0;

docs/examples_src/example_minimal.c

@@ -97,7 +97,7 @@ Minimal example code
 To verify proper library setup, minimal example has been prepared.
 Run it in your main application file to verify its proper execution
 
-.. literalinclude:: ../examples_src/example_minimal.c
+.. literalinclude:: ../../examples/example_minimal.c
     :language: c
     :linenos:
     :caption: Absolute minimum example

docs/get-started/index.rst

@@ -16,19 +16,21 @@ LwSHELL is lightweight dynamic memory manager optimized for embedded systems.
 Features
 ^^^^^^^^
 
-* Written in ANSI C99, compatible with ``size_t`` for size data types
-* Platform indenepdent
-* Implements simple shell interface targeting embedded systems
+* Lightweight commands shell for embedded systems
+* Platform independent and very easy to port
+
+    * Development of library under Win32 platform
+* Written in C language (C99)
+* No dynamic allocation, maximum number of commands assigned at compile time
 * Highly configurable
-* Includes number parsers for integers
-* Operating system ready
+* Simple help-text with `cmd -v` option
 * User friendly MIT license
 
 Requirements
 ^^^^^^^^^^^^
 
 * C compiler
-* Less than ``2kB`` of non-volatile memory
+* Less than ``5kB`` of non-volatile memory
 
 Contribute
 ^^^^^^^^^^

docs/index.rst

@@ -3,7 +3,59 @@
 How it works
 ============
 
-To be added...
+This section describes how library works from the basic perspective.
+
+LwSHELL is designed to accept *computer-command-like* input, in format of ``cmdname param1 "param 2 with space"``,
+parse it properly and search for function callback that is assigned for specific ``cmdname``.
+
+Library starts processing input line on *line-feed* or *carriage-return* characters.
+It splits tokens by space character:
+
+* Tokens must not include ``space`` character or it will be considered as multi-token input
+* To use *space* character as token input, encapsulate character in *double-quotes*
+
+Command structure
+^^^^^^^^^^^^^^^^^
+
+Every command has assigned dedicated name and must start with it.
+Application must take care to input exact command name since commands are case-sensitive, ``mycmd`` is a different command than ``Mycmd``.
+
+Command structure looks like:
+
+* It must start with command name and has at least one (``1``) parameter, eg. ``mycommand``. Command name is counted as first parameter
+* It may have additional parameters split with *space* character
+* Every input is parsed as string, even if parameter is string
+
+.. tip::
+    To use space as an input, encapsulate it with *double quotes*, eg. ``mycmd param1 "param 1 has spaces"``
+
+Register command
+^^^^^^^^^^^^^^^^
+
+Application must register command(s) to be used by the system.
+This can be done using :cpp:func:`lwshell_register_cmd` function which accepts
+*command name*, *command function* and optional *command description*
+
+Command description
+^^^^^^^^^^^^^^^^^^^
+
+Every command can have assigned its very simple description text, know as *help text*.
+Description is later accessible with special command input that has ``2`` parameters in total and second is ``-h``, ``cmdname -h``.
+
+Data output
+^^^^^^^^^^^
+
+To properly work with the library, application must input data to process by using :cpp:func:`lwshell_input` function.
+Thanks to the library implementation, it is possible to get data feedback and be able to implement OS-like console.
+
+To enable data-output feature, define your output callback function and assign it with :cpp:func:`lwshell_set_output_fn` function.
+
+Data outputs works on:
+
+* Special characters for *carriage return* and *line-feed*
+* Special character *backspace* that returns set of characters to implement backspace-like event on your output
+* Actual input character printed back for user feedback
+* ``cmdname -h`` feature works to print simple help text
 
 .. toctree::
     :maxdepth: 2

docs/user-manual/how-it-works.rst

@@ -0,0 +1,31 @@
+#include <string.h>
+#include "lwshell/lwshell.h"
+
+/* Command to get called */
+int32_t
+mycmd_fn(int32_t argc, char** argv) {
+    printf("mycmd_fn called. Number of argv: %d\r\n", (int)argc);
+    for (int32_t i = 0; i < argc; ++i) {
+        printf("ARG[%d]: %s\r\n", (int)argc, argv[i]);
+    }
+
+    /* Successful execution */
+    return 0;
+}
+
+/* Example code */
+void
+example_minimal(void) {
+    const char* input_str = "mycmd param1 \"param 2 with space\"";
+
+    /* Init library */
+    lwshell_init();
+
+    /* Define shell commands */
+    lwshell_register_cmd("mycmd", mycmd_fn, "Adds 2 integer numbers and prints them");
+
+    /* User input to process every character */
+
+    /* Now insert input */
+    lwshell_input(input_str, strlen(input_str));
+}

examples/example_minimal.c

@@ -55,28 +55,25 @@ typedef struct {
     lwshell_cmd_fn fn;                          /*!< Command function to call on match */
     const char* name;                           /*!< Command name to search for match */
     const char* desc;                           /*!< Command description for help */
-#if 0
-    char cmd_name[LWSHELL_CFG_MAX_CMD_NAME_LEN + 1];    
-#endif /* 0 */
 } lwshell_cmd_t;
 
 /* Array of all commands */
 static lwshell_cmd_t cmds[LWSHELL_CFG_MAX_CMDS];
 static size_t cmds_cnt;
 static lwshell_t shell;
 
-/**
- * \brief           Get shell from input
- */
+/* Get shell instance from input */
 #define LWSHELL_GET_LW(lw)          ((lw) != NULL ? (lw) : (&shell))
 
+ /* Add character to instance */
 #define LWSHELL_ADD_CH(lw, ch)      do {            \
     if ((lw)->buff_ptr < (LWSHELL_ARRAYSIZE(lw->buff) - 1)) {   \
         (lw)->buff[(lw)->buff_ptr] = ch;            \
         (lw)->buff[++(lw)->buff_ptr] = '\0';        \
     }                                               \
 } while (0)
 
+/* Reset buffers */
 #define LWSHELL_RESET_BUFF(lw)      do {            \
     memset((lw)->buff, 0x00, sizeof((lw)->buff));   \
     memset((lw)->argv, 0x00, sizeof((lw)->argv));   \
@@ -187,8 +184,6 @@ prv_parse_input(lwshell_t* lw) {
 
 /**
  * \brief           Initialize shell interface
- * \param[in]       out_fn: Output function to print library data. 
- *                      Set to `NULL` if not used
  * \return          \ref lwshellOK on success, member of \ref lwshellr_t otherwise
  */
 lwshellr_t