Fixed documentation. Updated README.md.

README.md

@@ -6,33 +6,47 @@ Simple Array C Library
 The methods accessible to the user (the non `static` ones) are the ones 
 described in `salibc.h`.
 
-To generate the ducumentation, you need to install `doxygen`, `texlive-core` 
-and `texlive-latexextra` (these are the names under Parabola GNU/Linux-libre 
-distro). 
+The first thing to do i to move to the `src` directory:
+```
+$ cd src
+```
+
+To generate the documentation, you need to install the following packages:
+```
+doxygen
+texlive-core
+texlive-latexextra
+```
 
-You can then execute the following:
+These are the names under Parabola GNU/Linux-libre distro. 
+
+You can then execute the following if you are only interested in the HTML form:
 ```
-$ cd src && make doxygen && cd latex && make
+$ make doxygen
 ```
 
-This will generate both LaTeX (`src/latex/refman.pdf`) and HTML 
-(`src/html/index.html`) documentation. 
+Or, if you want a pdf file (`../refman.pdf`):
+```
+$ make doxygenlatex
+```
 
-If you are only interested in the HTML form you don't need to install the 
-LaTeX packages.
+You can also remove the whole documentation like this:
+```
+$ make cleandoxygen
+```
 
 The doxygen configuration file has been generated with the following:
 ```
 $ doxygen -g doxy.conf
 ```
 
-and then edited with the options I thought were useful.
+where `doxy.conf` was edited with the options I thought were useful.
 
 ##Test
 
 You can test the library with the following:
 ```
-$ cd src && make
+$ make
 ```
 
 This will generate an executable file called `salibc.out`.

src/Makefile

@@ -64,5 +64,11 @@ salibc: salibc.o salibc_test.o
 doxygen:
 	@doxygen doxy.conf
 
+doxygenlatex: doxygen
+	@cd latex; make pdf; mv refman.pdf ../../.; cd ..
+
+cleandoxygen:
+	@rm -rf html latex ../refman.pdf
+
 # to protect files with the following names, the .PHONY rule is used
 .PHONY: default all clean indent $(EXECUTABLES)

src/doxy.conf

@@ -66,7 +66,7 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = Simple C Array Library
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -438,7 +438,7 @@ LOOKUP_CACHE_SIZE      = 0
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = YES
+EXTRACT_ALL            = NO
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.
@@ -2000,7 +2000,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2040,7 +2040,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = DOXYGEN
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

src/salibc.c

@@ -1,4 +1,4 @@
-/**
+/*
  * @file salibc.c
  * @author Franco Masotti
  * @date 28 Apr 2016
@@ -92,16 +92,17 @@ element_null (void *element)
   return (element == NULL);
 }
 
+#if defined (MEMORY_OVERLAP_CHECK) || DOXYGEN
 /**
- * If this flag is defined memory_overlaps function will work normally,
+ * @brief If this flag is defined memory_overlaps function will work normally,
  * otherwise it will only return false. By default this flag is deactivated.
  */
-#ifdef MEMORY_OVERLAP_CHECK
+#define MEMORY_OVERLAP_CHECK
 
 /**
- * Since memory is not always allocated consecutively, the following controls 
- * may fail because the only check memory addresses and not if that memory 
- * belongs to something else.
+ * @note Since memory is not always allocated consecutively, the following
+ * controls may fail because only memory addresses are checked and the
+ * system does not know if the memory in between belongs to something else.
  */
 static bool
 memory_overlaps (void *chunk1, void *chunk2, size_t fullsize)
@@ -138,7 +139,8 @@ memory_overlaps (void *chunk1, void *chunk2, size_t fullsize)
  */
 
 /**
- * Delete the non-ADT part of the array (as well as some fields of the ADT).
+ * @note The non-ADT part of the array is deleted (as well as some fields of
+ * the ADT).
  */
 static void
 realarray_delete (Array a)
@@ -146,7 +148,6 @@ realarray_delete (Array a)
   if (array_null (a))
     return;
 
-  /* Free the real array. */
   free (array_pointer (a));
   a->ptr = NULL;
   a->nmemb = 0;
@@ -177,7 +178,7 @@ array_indexpointer (Array a, int index)
 }
 
 /**
- *  It is assumed that element has the same size of a->ptr.
+ * @note It is assumed that element has the same size of a->ptr.
  */
 static bool
 array_memcopy (Array a, int index, void *element)
@@ -186,10 +187,11 @@ array_memcopy (Array a, int index, void *element)
     return false;
 
   /**
-   * Even though the array_indexoutofbounds function is called inside the
+   * @note Even though the array_indexoutofbounds function is called inside the
    * array_indexpointer function, this returns NULL, so memcpy would be done
-   * on a dest of NULL.
+   * on a dest of NULL. That's why we need to call that function here as well
    */
+   /** @code */
   if (!element_null (element)
       && !memory_overlaps (a, element, array_fullsize (a))
       && !array_indexoutofbounds (a, index))
@@ -197,6 +199,7 @@ array_memcopy (Array a, int index, void *element)
       memcpy (array_indexpointer (a, index), element, array_size (a));
       return true;
     }
+  /** @endcode */
   else
     return false;
 }
@@ -229,7 +232,7 @@ array_length (Array a)
 }
 
 /**
- * This function should not return an out of bound value.
+ * @note This function should not return an out of bound value.
  */
 size_t
 array_fullsize (Array a)
@@ -248,7 +251,8 @@ array_pointer (Array a)
 }
 
 /**
- * memcmp works well in checking equality even for floating point numbers.
+ * @note memcmp works well in checking equality even for floating point
+ * numbers.
  */
 bool
 array_equal (Array a1, Array a2)
@@ -266,7 +270,7 @@ array_equal (Array a1, Array a2)
 }
 
 /**
- * Array constructor.
+ * @note This function is also known as the array constructor.
  */
 Array
 array_new (int nmemb, size_t size)
@@ -286,9 +290,6 @@ array_new (int nmemb, size_t size)
 	array_delete (&new_array);
     }
 
-  /**
-   * This may be NULL.
-   */
   return new_array;
 }
 
@@ -297,13 +298,7 @@ array_delete (Array * a_ref)
 {
   if (!element_null (a_ref) && !array_null (*a_ref))
     {
-      /**
-       * Free the real array.
-       */
       realarray_delete (*a_ref);
-      /**
-       * Free the ADT.
-       */
       (*a_ref)->size = 0;
       free (*a_ref);
       *a_ref = NULL;
@@ -332,7 +327,7 @@ array_set (Array a, void *element)
 }
 
 /**
- * This is an interface to array_indexpointer.
+ * @note This function is an interface to array_indexpointer.
  */
 char *
 array_get (Array a, int index)
@@ -350,18 +345,22 @@ array_copy (Array a1)
     return NULL;
 
   /**
-   * Allocate a new array with the same ADT characteristics.
+   * @note Allocate a new array with the same ADT characteristics.
    */
+  /** @code */
   a2 = array_new (array_length (a1), array_size (a1));
   if (array_null (a2))
     return NULL;
+  /** @endcode */
 
   /**
-   * Copy the real array using the previously defined functions.
+   * @note Copy the real array using the previously defined functions.
    */
+  /** @code */
   for (i = 0; i < array_length (a1); i++)
     if (!array_memcopy (a2, i, array_indexpointer (a1, i)))
       return NULL;
+  /** @endcode */
 
   return a2;
 }
@@ -375,30 +374,31 @@ array_resize (Array a, int new_length)
   if (array_null (a))
     return NULL;
 
-  /**
+  /** @code */
+  /*
    * Invalid new length.
    */
   if (new_length < 0)
     return false;
-  /**
-   * new_length is set to 0 -> leave ADT, but delete internal array.
+  /*
+   * new_length is set to zero, so leave the ADT, but delete internal array.
    */
   else if (new_length == 0)
     {
       realarray_delete (a);
       return true;
     }
-  /**
-   * Same size -> do nothing.
+  /*
+   * Same size as before, then do nothing.
    */
   else if (array_length (a) == new_length)
     return true;
-  /**
+  /*
    * Array's length != new_length, so realloc can now be used directly.
    */
   else
     {
-      /**
+      /*
        * Safe realloc (to avoid losing the stored array if realloc fails).
        */
       tmp =
@@ -409,7 +409,7 @@ array_resize (Array a, int new_length)
 	a->ptr = tmp;
       else
 	return false;
-      /**
+      /*
        * memset to 0 new part of the array.
        * To do this we must go to the first byte of the new array and put 0
        * until we get to (memdiff * a->size) bytes.
@@ -419,17 +419,18 @@ array_resize (Array a, int new_length)
 	memset (array_pointer (a) + array_fullsize (a) + array_size (a), 0,
 		((size_t) memdiff) * array_size (a));
 
-      /**
+      /*
        * Set the new array length.
        */
       a->nmemb = new_length;
     }
 
   return true;
+  /** @endcode */
 }
 
 /**
- * This function alters the input.
+ * @note This function alters the input.
  */
 bool
 array_append (Array a, void *element)
@@ -449,12 +450,14 @@ array_trim (Array a)
   int initial_length = array_length (a);
   char *element, *element_copy;
 
-  element = array_indexpointer (a, initial_length - 1);
   /**
-   * Copy *element int *element_copy.
+   * @note Copy *element int *element_copy.
    */
+  /** @code */
+  element = array_indexpointer (a, initial_length - 1);
   element_copy = malloc (array_size (a));
   memcpy (element_copy, element, array_size (a));
+  /** @endcode */
 
   if (!element_null (element_copy) && array_resize (a, initial_length - 1))
     return element_copy;
@@ -469,11 +472,13 @@ array_merge (Array a1, Array a2)
   int i, j, total_length = array_length (a1) + array_length (a2);
 
   /**
-   * Safety controls.
+   * @note Safety controls.
    */
+  /** @code */
   if ((array_null (a1) && array_null (a2)) || (array_size (a1) !=
 					       array_size (a2)))
     return NULL;
+  /** @endcode */
 
   new_array = array_new (total_length, array_size (a1));
   if (array_null (new_array))

src/salibc.h

@@ -28,6 +28,10 @@
  */
 
 #ifndef SALIBC
+
+/**
+ * @brief Include the main header.
+ */
 #define SALIBC
 
 /**
@@ -48,6 +52,10 @@
 
 /**
  * @brief Array Abstract Data Type.
+ *
+ * @struct Array
+ *
+ * @typedef struct Array *Array
  */
 typedef struct Array
 {

src/salibc_test.c

@@ -33,10 +33,10 @@
  * @brief if this flag is defined then the main function in this file is
  * included.
  */
-#ifdef SALIBC_TEST
+#if defined (SALIBC_TEST) || DOXYGEN
 
 /**
- * @brief Use:
+ * @note Use:
  * const MYVARIABLE = value
  * instead of:
  * value