documentation of modules trailer, types, xref

include/trailer.h

@@ -7,9 +7,21 @@
 
 #include "types.h"
 
-
+/** @brief Process the trailer section. Initial position in the PDF needs to be
+ *         at the beginning of that section
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t process_trailer(sigil_t *sgl);
 
+/** @brief Tests for trailer module
+ *
+ * @param verbosity output level - 0 means nothing, 1 prints module names with
+ *                  the overall module result, and 2 prints also each test inside
+ *                  of the module
+ * @return 0 if success, 1 if failed
+ */
 int sigil_trailer_self_test(int verbosity);
 
 #endif /* PDF_SIGIL_TRAILER_H */

include/types.h

@@ -16,20 +16,36 @@
     typedef SSIZE_T ssize_t;
 #endif
 
+/** @brief Error type with well-defined values used by most of the functions
+ *
+ */
 typedef uint32_t sigil_err_t;
 
+/** @brief Type used as an enumeration specifying dictionary key
+ *
+ */
 typedef uint32_t dict_key_t;
 
+/** @brief Type used as an indirect reference to object
+ *
+ */
 typedef struct {
     size_t object_num;
     size_t generation_num;
 } reference_t;
 
+/** @brief Type for storing the signature contents in hexadecimal
+ *
+ */
 typedef struct {
     char  *contents_hex;
     size_t capacity;
 } contents_t;
 
+/** @brief Type for storing a certificate in hexadecimal and X.509 form + pointer
+ *         to the next certificate (linked list)
+ *
+ */
 typedef struct cert_t {
     char     *cert_hex;
     X509     *x509;
@@ -37,6 +53,9 @@ typedef struct cert_t {
     struct cert_t *next;
 } cert_t;
 
+/** @brief Type for a range and pointer to the next one (linked list)
+ *
+ */
 typedef struct range_t {
     size_t start;
     size_t length;
@@ -48,12 +67,19 @@ typedef struct {
     size_t capacity;
 } ref_array_t;
 
+/** @brief Type for one entry from a cross-reference section and pointer to the
+ *         next one (linked list)
+ *
+ */
 typedef struct xref_entry_t {
     size_t byte_offset;
     size_t generation_num;
     struct xref_entry_t *next;
 } xref_entry_t;
 
+/** @brief Type for storing the entries from a cross-reference section
+ *
+ */
 typedef struct {
     xref_entry_t **entry;
     size_t         capacity;
@@ -61,6 +87,10 @@ typedef struct {
     size_t         prev_section;
 } xref_t;
 
+/** @brief Type for storing the PDF data. Allowing both - the file pointer
+ *         and the buffer
+ *
+ */
 typedef struct {
     FILE    *file;
     char    *buffer;
@@ -69,6 +99,10 @@ typedef struct {
     uint32_t deallocation_info;
 } pdf_data_t;
 
+/** @brief Sigil context for saving all the configuration, partial results during
+ *         verification process, and the final result
+ *
+ */
 typedef struct {
     // file data
     pdf_data_t         pdf_data;

include/xref.h

@@ -7,19 +7,54 @@
 
 #include "types.h"
 
-
+/** @brief Allocates a new xref structure and sets default values
+ *
+ * @return valid xref_t structure or NULL if error occured
+ */
 xref_t *xref_init(void);
 
+/** @brief Clean-up of the provided xref structure
+ *
+ * @param xref the structure to be freed
+ */
 void xref_free(xref_t *xref);
 
+/** @brief Read the offset of the last cross-reference section
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t read_startxref(sigil_t *sgl);
 
+/** @brief Reads all the entries from the cross-reference table to the context
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t read_xref_table(sigil_t *sgl);
 
+/** @brief Does processing of the cross-reference section - determines type and
+ *         reads the entries
+ *
+ * @param sgl context
+ * @return ERR_NONE if success
+ */
 sigil_err_t process_xref(sigil_t *sgl);
 
+/** @brief For debugging purposes - print all the data from the provided
+ *         cross-reference table
+ *
+ * @param xref input cross-reference table to be printed
+ */
 void print_xref(xref_t *xref);
 
+/** @brief Tests for the xref module
+ *
+ * @param verbosity output level - 0 means nothing, 1 prints module names with
+ *                  the overall module result, and 2 prints also each test inside
+ *                  of the module
+ * @return 0 if success, 1 if failed
+ */
 int sigil_xref_self_test(int verbosity);
 
 #endif /* PDF_SIGIL_XREF_H */

lib/trailer.c

@@ -66,16 +66,11 @@ int sigil_trailer_self_test(int verbosity)
 {
     print_module_name("trailer", verbosity);
 
-    // TEST: fn determine_xref_type - STREAM
-    print_test_item("fn process_trailer", verbosity);
-
-
-
-    print_test_result(1, verbosity);
+    // place for possible later tests
+    // ...
 
     // all tests done
     print_module_result(1, verbosity);
-
     return 0;
 
 failed:
@@ -83,4 +78,4 @@ failed:
     print_module_result(0, verbosity);
 
     return 1;
-}
+}
\ No newline at end of file