Doxygen comments.

3 files changed, 178 insertions, 32 deletions

diff --git a/src/hide_show.c b/src/hide_show.c
index 005db49..44fba0c 100644
--- a/src/hide_show.c
+++ b/src/hide_show.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 hide_show.c
+ * \author Andrés Martinelli <andmarti@gmail.com>
+ * \date 2017-07-18
+ * \brief TODO Write a tbrief file description.
+ */
+
 #include <stdlib.h>
 
 #include "sc.h"
@@ -12,7 +56,15 @@
 extern struct undo undo_item;
 #endif
 
-/* mark a row as hidden */
+/**
+ * \brief Mark a row as hidden
+ *
+ * \param[in] from_row
+ * \param[in] arg
+ *
+ * \return none
+ */
+
 void hide_row(int from_row, int arg) {
     register int r2;
 
@@ -43,7 +95,15 @@ void hide_row(int from_row, int arg) {
     return;
 }
 
-/* mark a column as hidden */
+/**
+ * \brief Mark a column as hidden
+ *
+ * \param[in] from_col
+ * \param[in] arg
+ *
+ * \return none
+ */
+
 void hide_col(int from_col, int arg) {
     int c2 = from_col + arg - 1;
     if (from_col < 0 || from_col > c2) {
@@ -74,7 +134,15 @@ void hide_col(int from_col, int arg) {
     return;
 }
 
-/* mark a row as not-hidden */
+/**
+ * \brief Mark a row as not-hidden
+ *
+ * \param[in] from_row
+ * \param[in] arg
+ *
+ * \return none
+ */
+
 void show_row(int from_row, int arg) {
     int r2 = from_row + arg - 1;
     if (from_row < 0 || from_row > r2) {
@@ -101,7 +169,15 @@ void show_row(int from_row, int arg) {
     return;
 }
 
-/* mark a column as not-hidden */
+/**
+ * \brief Mark a column as not-hidden
+ *
+ * \param[in] from_col
+ * \param[in] arg
+ *
+ * \return none
+ */
+
 void show_col(int from_col, int arg) {
     int c2 = from_col + arg - 1;
     if (from_col < 0 || from_col > c2) {
@@ -128,6 +204,12 @@ void show_col(int from_col, int arg) {
     return;
 }
 
+/**
+ * \brief TODO Document show_hiddenrows
+ *
+ * \return none
+ */
+
 void show_hiddenrows() {
     int r, c = 0;
     for (r = 0; r < maxrow; r++) {
@@ -144,6 +226,12 @@ void show_hiddenrows() {
     return;
 }
 
+/**
+ * \brief TODO Document show_hiddencols
+ *
+ * \return none
+ */
+
 void show_hiddencols() {
     int c, count = 0;
     for (c = 0; c < maxcol; c++) {
diff --git a/src/lex.c b/src/lex.c
index 36e9466..76e65ca 100644
--- a/src/lex.c
+++ b/src/lex.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 lex.c
+ * \author Andrés Martinelli <andmarti@gmail.com>
+ * \date 2017-07-18
+ * \brief TODO Write a tbrief file description.
+ */
+
 #include <sys/types.h>
 #include <string.h>
 #include <stdlib.h>
@@ -24,6 +68,12 @@ jmp_buf fpe_buf;
 
 bool decimal = FALSE;
 
+/**
+ * \brief TODO Document fpe_trap()
+ *
+ * \return none
+ */
+
 void fpe_trap(int signo) {
 #if defined(i386)
     asm("    fnclex");
@@ -51,6 +101,12 @@ struct key statres[] = {
 #include "tui.h"
 #include "range.h"
 
+/**
+ * \brief TODO Document yylex()
+ *
+ * \return none
+ */
+
 int yylex() {
     char * p = line + linelim;
     int ret = 0;
@@ -279,14 +335,19 @@ int yylex() {
     return ret;
 }
 
-/*
- * Given a token string starting with a symbolic column name and its valid
- * length, convert column name ("A"-"Z" or "AA"-"ZZ") to a column number (0-N).
- * Never mind if the column number is illegal (too high).  The procedure's name
- * and function are the inverse of coltoa().
+/**
+ * \brief TODO Document atocol()
  *
- * Case-insensitivity is done crudely, by ignoring the 040 bit.
+ * \details Given a token string starting with a symbolid column name and
+ * its valid length, convert column namd ("A"-"Z" or "AA"-"ZZ") to a
+ * column number (0-N). Never mind if the column number is illegal
+ * (too high). The procedure's name and function are the inverse of coltoa().
+ *
+ * \details Case-insensitivity is done crudely, but ignoring the 040 bit.
+ *
+ * \return none
  */
+
 int atocol(char *string, int len) {
     register int col;
 
diff --git a/src/lua.c b/src/lua.c
index 8ca45df..313b57f 100644
--- a/src/lua.c
+++ b/src/lua.c
@@ -54,10 +54,10 @@
  * Those are then accessible also  when called via @lua cmd or in triggers.
  */
 
-#include <lua.h>        /* Always include this when calling Lua */
-#include <lauxlib.h>    /* Always include this when calling Lua */
-#include <lualib.h>     /* Prototype for luaL_openlibs(),       */
-                        /* always include this when calling Lua */
+#include <lua.h>                                /* Always include this when calling Lua */
+#include <lauxlib.h>                            /* Always include this when calling Lua */
+#include <lualib.h>                             /* Prototype for luaL_openlibs(),       */
+                                                /* always include this when calling Lua */
 #include <ctype.h>
 #include <unistd.h>
 #include <stdlib.h>
@@ -88,7 +88,7 @@ lua_State *L;
  *
  * \param[in] L
  *
- * \return none
+ * \return number of results; 0 otherwise
  */
 
 static int l_getnum (lua_State *L) {
@@ -109,7 +109,7 @@ static int l_getnum (lua_State *L) {
 }
 
 /**
- * \brief TODO Document l_setnum
+ * \brief TODO Document l_setnum()
  *
  * \param[in] L
  *
@@ -160,12 +160,11 @@ static int l_setstr (lua_State *L) {
     return 0;
 }
 
+
 /**
  * \brief TODO Document l_getstr
  *
- * \param[in] L
- *
- * \return none
+ * \return
  */
 
 static int l_getstr (lua_State *L) {
@@ -189,9 +188,7 @@ static int l_getstr (lua_State *L) {
 }
 
 /**
- * \brief TODO <brief function description>
- *
- * \param[in] L
+ * \brief TODO Document l_setform()
  *
  * \return none
  */
@@ -212,7 +209,6 @@ static int l_setform (lua_State *L) {
  * \brief TODO Document l_sc
  *
  * \param[in] L
- *
  * \return none
  */
 
@@ -229,7 +225,7 @@ static int l_sc (lua_State *L) {
  *
  * \param[in] L
  *
- * returns: none
+ * \return none
  */
 
 static int l_colrow2a(lua_State *L) {
@@ -355,7 +351,7 @@ void doLuaclose() {
 }
 
 /**
- * \brief TODO Document doLUA
+ * \brief TODO Document doLUA()
  *
  * \param[in] se
  *
@@ -384,7 +380,7 @@ char * doLUA( struct enode * se) {
 }
 
 /**
- * \brief TODO Document doLuaTriger()
+ * \brief TODO Document duLuaTriger
  *
  * \return none
  */
@@ -437,16 +433,17 @@ void doLuaTriger2(int row, int col, int flags) {
     return;
 }
 
+/*
+ * Lua trigger on a particular cell
+ * we assume file and function ist correct other lua throught an error
+ */
 /**
  * \brief TODO Document doLuaTrigger_cell()
  *
- * \details Lua trigger on a particular cell. We assum file and
- * function ist correct other lua throught an error
- * 
- * \param[in] p
- * \param[in] flags
+ * \details Lua trigger on a particular cell. We assume file and
+ * function ist correct. Otherwise, Lua throes an error
  *
- * returns: none
+ * \return: none
  */
 
 void doLuaTrigger_cell(struct ent *p, int flags) {