Doxygen comments.

2 files changed, 245 insertions, 28 deletions

diff --git a/src/buffer.c b/src/buffer.c
index 45f6c0d..d3ed274 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -1,3 +1,47 @@
+/*******************************************************************************
+ * Copyright (c) 2013-2017, Andrés Martinelli <andmarti@gmail.com              *
+ * All rights reserved.                                                        *
+ *                                                                             *
+ * This file is a part of SC-IM                                                *
+ *                                                                             *
+ * SC-IM is a spreadsheet program that is based on SC. The original authors    *
+ * of SC are James Gosling and Mark Weiser, and mods were later added by       *
+ * Chuck Martin.                                                               *
+ *                                                                             *
+ * Redistribution and use in source and binary forms, with or without          *
+ * modification, are permitted provided that the following conditions are met: *
+ * 1. Redistributions of source code must retain the above copyright           *
+ *    notice, this list of conditions and the following disclaimer.            *
+ * 2. Redistributions in binary form must reproduce the above copyright        *
+ *    notice, this list of conditions and the following disclaimer in the      *
+ *    documentation and/or other materials provided with the distribution.     *
+ * 3. All advertising materials mentioning features or use of this software    *
+ *    must display the following acknowledgement:                              *
+ *    This product includes software developed by Andrés Martinelli            *
+ *    <andmarti@gmail.com>.                                                    *
+ * 4. Neither the name of the Andrés Martinelli nor the                        *
+ *   names of other contributors may be used to endorse or promote products    *
+ *   derived from this software without specific prior written permission.     *
+ *                                                                             *
+ * THIS SOFTWARE IS PROVIDED BY ANDRES MARTINELLI ''AS IS'' AND ANY            *
+ * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED   *
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE      *
+ * DISCLAIMED. IN NO EVENT SHALL ANDRES MARTINELLI BE LIABLE FOR ANY           *
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES  *
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;*
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND *
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT  *
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE       *
+ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.           *
+ *******************************************************************************/
+
+/**
+ * \file buffer.c
+ * \author Andrés Martinelli <andmarti@gmail.com>
+ * \date 2017-07-18
+ * \brief TODO Write a brief file description.
+ */
+
 #include <stdlib.h>
 #include <wchar.h>
 
@@ -5,7 +49,12 @@
 #include "macros.h"
 #include "utils/string.h"
 
-// Create buffer as list of blocks
+/**
+* \brief Create buffer as list of blocks 
+*
+* \return b
+*/
+
 struct block * create_buf() {
     struct block * b = (struct block *) malloc(sizeof(struct block));
     b->value = '\0';
@@ -13,7 +62,15 @@ struct block * create_buf() {
     return b;
 }
 
-// Add an wint_t to a buffer
+/**
+* \brief Add a wint_t to a buffer
+*
+* \param[in] buf
+* \param[in] d
+*
+* \return none
+*/
+
 void addto_buf(struct block * buf, wint_t d) {
     struct block * aux = buf;
 
@@ -31,7 +88,15 @@ void addto_buf(struct block * buf, wint_t d) {
     return;
 }
 
-// Replace the elements of "origen" buffer to "destino" buffer
+/**
+* \brief Replace the elements of "origen" buffer to "destino" buffer
+*
+* \param[in] origen
+* \param[in] destino
+*
+* \return none
+*/
+
 void copybuffer(struct block * origen, struct block * destino) {
     flush_buf(destino);
     int len = get_bufsize(origen);
@@ -41,8 +106,16 @@ void copybuffer(struct block * origen, struct block * destino) {
     return;
 }
 
-// Replace the element of a buffer at 'pos' with a '\0'
-//FIXME
+/**
+* \brief Replace the element of a buffer at 'pos' with a '\0'
+*
+* \param[in] buf
+* \param[in] pos
+*
+* \return none
+*/
+
+// FIXME
 void del_buf (struct block * buf, int pos) {
     int i;
     struct block * ant = buf;
@@ -62,6 +135,14 @@ void del_buf (struct block * buf, int pos) {
     return;
 }
 
+/**
+* \brief TODO Document fludh_buf()
+*
+* \param[in] buf
+*
+* \return none
+*/
+
 void flush_buf (struct block * buf) {
     if (buf == NULL) return;
 
@@ -77,15 +158,30 @@ void flush_buf (struct block * buf) {
     return;
 }
 
-// Delete all blocks of a buffer
-// including the initial node
+/**
+* \brief Delete all blocks of a buffer including the initial node
+*
+* \details Delete all blocks of a buffer including the initial node
+*
+* \param buf
+*
+* \return none
+*/
+
 void erase_buf (struct block * buf) {
     flush_buf(buf);
     free(buf);
     return;
 }
 
-// get size of buffer (included special chars)
+/**
+* \brief Get size of buffer (indlucded special chars)
+*
+* \param[in] buf
+*
+* \return c size of buffer
+*/
+
 int get_bufsize(struct block * buf) {
     struct block * b_aux = buf;
     if (b_aux == NULL || b_aux->value == '\0') return 0;
@@ -97,8 +193,17 @@ int get_bufsize(struct block * buf) {
     return c;
 }
 
-// get printable buffer lenght (excluded special chars)
-// (special chars should never be printed in screen)
+/**
+* \brief Get printable buffer length (excluded special chars)
+*
+* \details Get printable bufferlength, which excludes special characters
+* as they should never be printed to a screen.
+*
+* \param[in] buf
+*
+* \return c printable buffer length
+*/
+
 int get_pbuflen(struct block * buf) {
     struct block * b_aux = buf;
     if (b_aux == NULL || b_aux->value == '\0') return 0;
@@ -110,7 +215,15 @@ int get_pbuflen(struct block * buf) {
     return c;
 }
 
-// return the int value of the n block
+/**
+* \brief Return the int value of n block
+*
+* \param[in] buf
+* \param[in] d
+*
+* \return none
+*/
+
 int get_bufval(struct block * buf, int d) {
     int i;
     struct block * b_aux = buf;
@@ -120,7 +233,14 @@ int get_bufval(struct block * buf, int d) {
     return b_aux->value;
 }
 
-// return if an int value is found in a buffer
+/**
+* \brief Return an int value if found in a buffer
+*
+* \details Search a buffer for a given integer value.
+*
+* \return 0 if not found, 1 if found
+*/
+
 int find_val(struct block * buf, int value) {
     struct block * b_aux = buf;
     while ( b_aux != NULL && b_aux->value != '\0' ) {
@@ -130,7 +250,14 @@ int find_val(struct block * buf, int value) {
     return 0; 
 }
 
-// Delete the first element in a buffer
+/**
+* \brief Delete the first element in a buffer
+*
+* \param[in] buf
+*
+* \return none
+*/
+
 struct block * dequeue (struct block * buf) {
     if (buf == NULL) return buf;
     struct block * sig;
diff --git a/src/input.c b/src/input.c
index e0871f8..bc0ab98 100644
--- a/src/input.c
+++ b/src/input.c
@@ -1,3 +1,47 @@
+/*******************************************************************************
+ * Copyright (c) 2013-2017, Andrés Martinelli <andmarti@gmail.com              *
+ * All rights reserved.                                                        *
+ *                                                                             *
+ * This file is a part of SC-IM                                                *
+ *                                                                             *
+ * SC-IM is a spreadsheet program that is based on SC. The original authors    *
+ * of SC are James Gosling and Mark Weiser, and mods were later added by       *
+ * Chuck Martin.                                                               *
+ *                                                                             *
+ * Redistribution and use in source and binary forms, with or without          *
+ * modification, are permitted provided that the following conditions are met: *
+ * 1. Redistributions of source code must retain the above copyright           *
+ *    notice, this list of conditions and the following disclaimer.            *
+ * 2. Redistributions in binary form must reproduce the above copyright        *
+ *    notice, this list of conditions and the following disclaimer in the      *
+ *    documentation and/or other materials provided with the distribution.     *
+ * 3. All advertising materials mentioning features or use of this software    *
+ *    must display the following acknowledgement:                              *
+ *    This product includes software developed by Andrés Martinelli            *
+ *    <andmarti@gmail.com>.                                                    *
+ * 4. Neither the name of the Andrés Martinelli nor the                        *
+ *   names of other contributors may be used to endorse or promote products    *
+ *   derived from this software without specific prior written permission.     *
+ *                                                                             *
+ * THIS SOFTWARE IS PROVIDED BY ANDRES MARTINELLI ''AS IS'' AND ANY            *
+ * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED   *
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE      *
+ * DISCLAIMED. IN NO EVENT SHALL ANDRES MARTINELLI BE LIABLE FOR ANY           *
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES  *
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;*
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND *
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT  *
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE       *
+ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.           *
+ *******************************************************************************/
+
+/**
+ * \file input.c
+ * \author Andrés Martinelli <andmarti@gmail.com>
+ * \date 2017-07-18
+ * \brief TODO Write a tbrief file description.
+ */
+
 #include <sys/time.h>
 #include <string.h>
 #include <ctype.h>   // for isdigit
@@ -22,12 +66,18 @@ int cmd_multiplier = 0;    // Multiplier
 int cmd_pending = 0;       // Command pending
 int shall_quit;            // Break loop if ESC key is pressed
 
-/*
- * Reads stdin for a valid command.
- * Details: Read characters from stdin to a input buffer.
- * When filled up, validate the command and call the appropriate handler.
- * When a timeout is reached, flush the buffer.
+/**
+ * \brief Reads stdin for a valid command
+ *
+ * \details Read characters from stdin to an input buffer. When filled,
+ * validate the command and call the appropriate handler. When a timeout
+ * is reached, flush the buffer.
+ *
+ * \param buffer
+ *
+ * \return none
  */
+
 void handle_input(struct block * buffer) {
     struct timeval start_tv, m_tv; // For measuring timeout
     gettimeofday(&start_tv, NULL);
@@ -113,7 +163,12 @@ void handle_input(struct block * buffer) {
     return;
 }
 
-// Break waiting command loop
+/**
+ * \brief Break waiting command loop
+ *
+ * \return none
+ */
+
 void break_waitcmd_loop(struct block * buffer) {
     if (curmode == COMMAND_MODE) {
 #ifdef HISTORY_FILE
@@ -154,10 +209,17 @@ void break_waitcmd_loop(struct block * buffer) {
     return;
 }
 
-/*
- * Handle timeout depending on the current mode
- * there is NO timeout for COMMAND, INSERT and EDIT modes.
+/**
+ * \brief Handle timeout depending on the current mode
+ *
+ * Handle timeout depending on the current mode. There is NO timeout
+ * for COMMAND, INSERT, and EDIT modes.
+ *
+ * \param[in] start_tv
+ *
+ * \return none
  */
+
 void fix_timeout(struct timeval * start_tv) {
     switch (curmode) {
         case COMMAND_MODE:
@@ -172,10 +234,17 @@ void fix_timeout(struct timeval * start_tv) {
     return;
 }
 
-/*
- * Traverse 'stuffbuff' and determines if there  is a valid command
- * Ej. buffer = "diw"
+/**
+ * \brief Traverse 'stuffbuff' and determine if there is a valid command.
+ *
+ * Traverse 'stuffbuff' and determine if there is a valid
+ * command (e.g. buffer = "diw").
+ *
+ * \param[in]buf
+ * \param[in]timeout
+ * \return none
  */
+
 int has_cmd (struct block * buf, long timeout) {
     int len = get_bufsize(buf);
     if ( ! len ) return 0;
@@ -198,7 +267,14 @@ void do_insertmode(struct block * sb);
 void do_editmode(struct block * sb);
 void do_visualmode(struct block * sb);
 
-// Use specific functions for every command on each mode
+/**
+ * \brief Use specific functions for every command on each mode
+ *
+ * \param[in] sb
+ *
+ * \return none
+ */
+
 void exec_single_cmd (struct block * sb) {
     switch (curmode) {
         case NORMAL_MODE:
@@ -220,7 +296,16 @@ void exec_single_cmd (struct block * sb) {
     return;
 }
 
-// Handle the final command to be executed, using the multiplier
+/**
+ * \brief Handle the final command to be executed, using the multiplier
+ *
+ * \param[in] cmd_multiplier
+ * \param[in] buf
+ * \param[in] timeout
+ *
+ * \return none
+ */
+
 void handle_mult(int * cmd_multiplier, struct block * buf, long timeout) {
     int j, k;
     struct block * b_copy = buf;
@@ -242,7 +327,12 @@ void handle_mult(int * cmd_multiplier, struct block * buf, long timeout) {
     return;
 }
 
-// Handle multiple command execution in sequence
+/**
+ * \brief Handle multiple command execution in sequence
+ *
+ * \return none
+ */
+
 void exec_mult (struct block * buf, long timeout) {
     int k, res, len = get_bufsize(buf);
     if ( ! len ) return;