added license information and started adding doxygen comments

LICENSE

@@ -1,5 +1,6 @@
 MIT License
-Copyright (c) <year> <copyright holders>
+
+Copyright (c) 2019 Stefan Strobel <stefan.strobel@shimatta.net>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

api/shellmatta.h

@@ -1,41 +1,93 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2019 Stefan Strobel <stefan.strobel@shimatta.net>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
+ * THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+ * @file shellmatta.h
+ * @brief API definition of the Shellmatta terminal implementation
+ * @author Stefan Strobel <stefan.strobel@shimatta.net>
+ */
+
+/**
+ * @addtogroup shellmatta
+ * @{
+ */
+
+#ifndef _SHELLMATTA_H_
+#define _SHELLMATTA_H_
 
 #include <stdint.h>
 
+/**
+ * @brief definition of shellmatta return codes
+ */
 typedef enum
 {
-	  SHELLMATTA_OK = 0u
-	, SHELLMATTA_ERROR
-	, SHELLMATTA_CONTINUE
-	, SHELLMATTA_USE_FAULT
+    SHELLMATTA_OK           = 0u,   /**< everything is OK               */
+    SHELLMATTA_ERROR            ,   /**< error occured                  */
+    SHELLMATTA_CONTINUE         ,   /**< the function is not over       */
+    SHELLMATTA_USE_FAULT            /**< parameter error - wrong usage  */
 } shellmatta_retCode_t;
 
+/**
+ * @brief shellmatta command function definition
+ */
 typedef shellmatta_retCode_t (*shellmatta_cmdFct_t)(int argc, char *argv[]);
 
+/**
+ * @brief structure of one shellmatta command
+ */
 typedef struct shellmatta_cmd
 {
-	char *cmd;
-	char *cmdAlias;
-	char *helpText;
-	char *usageText;
-	shellmatta_cmdFct_t cmdFct;
-	struct shellmatta_cmd *next;
+    char *cmd;                      /**< command name                           */
+    char *cmdAlias;                 /**< command alias                          */
+    char *helpText;                 /**< help text to print in "help" command   */
+    char *usageText;                /**< usage text to print on parameter error */
+    shellmatta_cmdFct_t cmdFct;     /**< pointer to the cmd callack function    */
+    struct shellmatta_cmd *next;    /**< pointer to next command or NULL        */
 } shellmatta_cmd_t;
 
+/**
+ * @brief structure of one shellmatta instance
+ */
 typedef struct
 {
-	uint8_t *buffer;
-	uint32_t bufferSize;
-	uint32_t bufferWritePointer;
-	uint32_t bufferReadPointer;
-	uint8_t *historyBuffer;
-	uint32_t historyBufferSize;
-	shellmatta_cmd_t *cmdList;
+    uint8_t *buffer;                /**< input buffer                           */
+    uint32_t bufferSize;            /**< size of the input buffer               */
+    uint32_t bufferWritePointer;    /**< offset of the current write operation  */
+    uint32_t bufferReadPointer;     /**< offset of the current read operation   */
+    uint8_t *historyBuffer;         /**< buffer to store the last commands      */
+    uint32_t historyBufferSize;     /**< size of the history buffer             */
+    shellmatta_cmd_t *cmdList;      /**< pointer to the first command           */
 } shellmatta_instance_t;
 
-extern void shellmatta_doInit(shellmatta_instance_t *inst, uint8_t *buffer, uint32_t bufferSize, uint8_t *historyBuffer, uint32_t historyBufferSize);
-extern void shellmatta_addCmd(shellmatta_instance_t *inst, shellmatta_cmd_t *cmd);
-extern void shellmatta_doTask(shellmatta_instance_t *inst, uint32_t time);
-extern void shellmatta_processData(shellmatta_instance_t *inst, char *data, uint32_t size);
-extern void shellmatta_printf(shellmatta_instance_t *inst, const char *fmt, ...);
-extern void shellmatta_getArg(uint32_t cnt, uint8_t *arg);
+void shellmatta_doInit(shellmatta_instance_t *inst, uint8_t *buffer, uint32_t bufferSize, uint8_t *historyBuffer, uint32_t historyBufferSize);
+void shellmatta_addCmd(shellmatta_instance_t *inst, shellmatta_cmd_t *cmd);
+void shellmatta_doTask(shellmatta_instance_t *inst, uint32_t time);
+void shellmatta_processData(shellmatta_instance_t *inst, char *data, uint32_t size);
+void shellmatta_printf(shellmatta_instance_t *inst, const char *fmt, ...);
+void shellmatta_getArg(uint32_t cnt, uint8_t *arg);
+
+#endif
 
+/** @} */

src/shellmatta.c

@@ -1,91 +1,147 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2019 Stefan Strobel <stefan.strobel@shimatta.net>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
+ * THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/**
+ * @file shellmatta.c
+ * @brief Main implementation of the Shellmatta terminal implementation
+ * @author Stefan Strobel <stefan.strobel@shimatta.net>
+ */
+
+/**
+ * @addtogroup shellmatta
+ * @{
+ */
 
 #include "shellmatta.h"
 #include <stdio.h>
 #include <stddef.h>
 #include <string.h>
 
-void shellmatta_doInit(shellmatta_instance_t *inst, uint8_t *buffer, uint32_t bufferSize, uint8_t *historyBuffer, uint32_t historyBufferSize)
+/**
+ * @brief initialize the shellmatta terminal and provide all callbacks
+ * @param[in,out]   inst                pointer to a shellmatta instance
+ * @param[in]       buffer              pointer to the input buffer to use
+ * @param[in]       bufferSize          size of the provided input buffer
+ * @param[in]       historyBuffer       pointer to the history buffer to use
+ *                                      NULL in case of no history buffer
+ * @param[in]       historyBufferSize   size of the history buffer
+ *                                      0 in case of no history buffer
+ */
+void shellmatta_doInit(
+        shellmatta_instance_t *inst,
+        uint8_t *buffer,
+        uint32_t bufferSize,
+        uint8_t *historyBuffer,
+        uint32_t historyBufferSize)
 {
-	inst->buffer = buffer;
-	inst->bufferSize = bufferSize;
-	inst->bufferReadPointer = 0u;
-	inst->bufferWritePointer = 0u;
-	inst->cmdList = NULL;
-	inst->historyBuffer = historyBuffer;
-	inst->historyBufferSize = historyBufferSize;
+    /** - copy all provided buffers into the shellmatta instance */
+    inst->buffer = buffer;
+    inst->bufferSize = bufferSize;
+    inst->bufferReadPointer = 0u;
+    inst->bufferWritePointer = 0u;
+    inst->cmdList = NULL;
+    inst->historyBuffer = historyBuffer;
+    inst->historyBufferSize = historyBufferSize;
 }
 
+
 void shellmatta_addCmd(shellmatta_instance_t *inst, shellmatta_cmd_t *cmd)
 {
-	shellmatta_cmd_t *tempCmd = inst->cmdList;
-
-	if(NULL == tempCmd)
-	{
-		inst->cmdList = cmd;
-		cmd->next = NULL;
-	}
-	else
-	{
-		while(tempCmd->next != NULL)
-		{
-			tempCmd = tempCmd->next;
-		}
-		tempCmd->next = cmd;
-		cmd->next = NULL;
-	}
+    shellmatta_cmd_t *tempCmd = inst->cmdList;
+
+    if (NULL == tempCmd)
+    {
+        inst->cmdList = cmd;
+        cmd->next = NULL;
+    }
+    else
+    {
+        while (tempCmd->next != NULL)
+        {
+            tempCmd = tempCmd->next;
+        }
+        tempCmd->next = cmd;
+        cmd->next = NULL;
+    }
 }
 
+
 void shellmatta_doTask(shellmatta_instance_t *inst, uint32_t time)
 {
 
 }
 
-void shellmatta_processData(shellmatta_instance_t *inst, char *data, uint32_t size)
+void shellmatta_processData(shellmatta_instance_t *inst, char *data,
+        uint32_t size)
 {
-	printf("%c", *data);
-
-	if(0x0A == *data)
-	{
-		shellmatta_cmd_t *cmd = inst->cmdList;
-		uint8_t cmdExecuted = 0u;
-		inst->buffer[inst->bufferWritePointer] = 0u;
-
-		while(NULL != cmd)
-		{
-			if(0 == strcmp(inst->buffer, cmd->cmd))
-			{
-				cmdExecuted = 1u;
-				char *blubb[10];
-				blubb[0] = inst->buffer;
-				cmd->cmdFct(1, blubb);
-				cmd = NULL;
-			}
-			else
-			{
-				cmd = cmd->next;
-			}
-		}
-
-		if(cmdExecuted == 0u)
-		{
-			printf("failed to find command");
-		}
-
-		inst->bufferWritePointer = 0u;
-	}
-	else
-	{
-		inst->buffer[inst->bufferWritePointer] = *data;
-		inst->bufferWritePointer ++;
-	}
+    printf("%c", *data);
+
+    if (0x0A == *data)
+    {
+        shellmatta_cmd_t *cmd = inst->cmdList;
+        uint8_t cmdExecuted = 0u;
+        inst->buffer[inst->bufferWritePointer] = 0u;
+
+        while (NULL != cmd)
+        {
+            if (0 == strcmp(inst->buffer, cmd->cmd))
+            {
+                cmdExecuted = 1u;
+                char *blubb[10];
+                blubb[0] = inst->buffer;
+                cmd->cmdFct(1, blubb);
+                cmd = NULL;
+            }
+            else
+            {
+                cmd = cmd->next;
+            }
+        }
+
+        if (cmdExecuted == 0u)
+        {
+            printf("failed to find command");
+        }
+
+        inst->bufferWritePointer = 0u;
+    }
+    else
+    {
+        inst->buffer[inst->bufferWritePointer] = *data;
+        inst->bufferWritePointer++;
+    }
 }
 
 void shellmatta_printf(shellmatta_instance_t *inst, const char *fmt, ...)
 {
-	printf(fmt);
+    /*TODO dummy implementation, shall be replaced by a generic output mechanism */
+    printf(fmt);
 }
 
 void shellmatta_getArg(uint32_t cnt, uint8_t *arg)
 {
 
 }
+
+/** @} */