m + add some documentation

Signed-off-by: Mattias Andrée <maandree@kth.se>

6 files changed, 80 insertions, 12 deletions

diff --git a/LICENSE b/LICENSE
index c44b2d9..ad865fe 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
 ISC License
 
-© 2021 Mattias Andrée <maandree@kth.se>
+© 2021, 2023 Mattias Andrée <maandree@kth.se>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above
diff --git a/demo.c b/demo.c
index 3181455..4a6cf10 100644
--- a/demo.c
+++ b/demo.c
@@ -1,3 +1,4 @@
+/* See LICENSE file for copyright and license details. */
 #include "libparsepcf.h"
 #include <fcntl.h>
 #include <stdio.h>
diff --git a/libparsepcf.h b/libparsepcf.h
index b3731d6..6931898 100644
--- a/libparsepcf.h
+++ b/libparsepcf.h
@@ -9,10 +9,47 @@
 /* Based on documentation from FontForge: https://fontforge.org/docs/techref/pcf-format.html */
 
 
+
+/**
+ * Table metadata
+ */
 struct libparsepcf_table {
+	/**
+	 * The table type, support values are:
+	 * - LIBPARSEPCF_PROPERTIES
+	 * - LIBPARSEPCF_ACCELERATORS
+	 * - LIBPARSEPCF_METRICS
+	 * - LIBPARSEPCF_BITMAPS
+	 * - LIBPARSEPCF_INK_METRICS
+	 * - LIBPARSEPCF_BDF_ENCODINGS
+	 * - LIBPARSEPCF_SWIDTHS
+	 * - LIBPARSEPCF_GLYPH_NAMES
+	 * - LIBPARSEPCF_BDF_ACCELERATORS
+	 * 
+	 * (The set in these values are non-overlapping,
+	 * however they cannot be combined.)
+	 */
 	uint32_t type;
+
+	/**
+	 * How the data in the table is formatted
+	 * 
+	 * This is only unsed internally, and supported
+	 * values are not exposed the the user
+	 */
 	uint32_t format;
+
+	/**
+	 * The size of the table
+	 */
 	uint32_t size;
+
+	/**
+	 * The table's offset in the file
+	 * 
+	 * (The file is padded with NUL bytes to align
+	 * each table to a 4 byte boundary)
+	 */
 	uint32_t offset;
 };
 
@@ -27,10 +64,37 @@ struct libparsepcf_table {
 #define LIBPARSEPCF_GLYPH_NAMES      (UINT32_C(1) << 7)
 #define LIBPARSEPCF_BDF_ACCELERATORS (UINT32_C(1) << 8)
 
-int libparsepcf_get_table_count(const char *, size_t, size_t *countp);
-int libparsepcf_get_tables(const char *, size_t, struct libparsepcf_table *tables, size_t first, size_t count);
-
-
+/**
+ * Get the number of tables in the file
+ * 
+ * @param   file    The file content
+ * @param   size    The file size
+ * @param   countp  Output parameter for the number of tables in the file
+ * @return          0 on success, -1 on failure
+ * 
+ * @throws  EBFONT  The file is not a properly formatted PCF file
+ */
+int libparsepcf_get_table_count(const char *, size_t, size_t *);
+
+/**
+ * Get table metadata from the file
+ * 
+ * @param   file    The file content
+ * @param   size    The file size
+ * @param   tables  Output buffer for the table metadata
+ * @param   first   The index of the first table to store in `tables`,
+ *                  the first table in the file has the index 0
+ * @param   count   The number of tables to store in `tables`;
+ *                  may not return the number of tables as retrieved
+ *                  by `libparsepcf_get_table_count`
+ * @return          0 on success, -1 on failure
+ * 
+ * @throws  EBFONT  The file is not a properly formatted PCF file
+ */
+int libparsepcf_get_tables(const char *, size_t, struct libparsepcf_table *, size_t, size_t);
+
+
+
 
 struct libparsepcf_properties {
 	size_t property_count;
@@ -57,6 +121,7 @@ int libparsepcf_get_property_subtable(const char *, size_t,
                                       struct libparsepcf_property_subtable *, size_t, size_t);
 
 
+
 
 struct libparsepcf_metrics {
 	int16_t left_side_bearing;
@@ -74,6 +139,7 @@ int libparsepcf_get_metrics(const char *, size_t,
                             struct libparsepcf_metrics *, size_t, size_t);
 
 
+
 
 struct libparsepcf_glyph_names {
 	size_t glyph_count;
@@ -91,6 +157,7 @@ int libparsepcf_get_glyph_name_subtable(const char *, size_t,
                                         const char **, size_t, size_t);
 
 
+
 
 struct libparsepcf_bitmaps {
 	size_t glyph_count;
@@ -112,6 +179,7 @@ int libparsepcf_get_bitmap_offsets(const char *, size_t,
                                    size_t *, size_t, size_t);
 
 
+
 
 struct libparsepcf_encoding {
 	uint16_t min_byte2;
@@ -146,6 +214,7 @@ int libparsepcf_get_glyph_indices(const char *, size_t,
                                   size_t *, size_t, size_t);
 
 
+
 
 struct libparsepcf_accelerators {
 	/**
@@ -195,6 +264,7 @@ int libparsepcf_get_swidth_count(const char *, size_t, const struct libparsepcf_
 int libparsepcf_get_swidths(const char *, size_t, const struct libparsepcf_table *, int32_t *, size_t, size_t);
 
 
+
 
 struct libparsepcf_font {
 	const struct libparsepcf_table *prob_table;
diff --git a/libparsepcf_get_accelerators.c b/libparsepcf_get_accelerators.c
index af3224a..b9688b7 100644
--- a/libparsepcf_get_accelerators.c
+++ b/libparsepcf_get_accelerators.c
@@ -2,7 +2,6 @@
 #include "common.h"
 
 
-
 int
 libparsepcf_get_accelerators(const char *file, size_t size,
                              const struct libparsepcf_table *table,
diff --git a/libparsepcf_parse_int16_from_unsigned__.c b/libparsepcf_parse_int16_from_unsigned__.c
index 3d61ef8..d4c0167 100644
--- a/libparsepcf_parse_int16_from_unsigned__.c
+++ b/libparsepcf_parse_int16_from_unsigned__.c
@@ -5,9 +5,8 @@
 int16_t
 libparsepcf_parse_int16_from_unsigned__(uint16_t u)
 {
-	if (u & UINT16_C(0x8000)) {
+	if (u & UINT16_C(0x8000))
 		return (int16_t)(uint16_t)~u - 1;
-	} else {
+	else
 		return (int16_t)u;
-	}
 }
diff --git a/libparsepcf_parse_int32_from_unsigned__.c b/libparsepcf_parse_int32_from_unsigned__.c
index 37de799..b446004 100644
--- a/libparsepcf_parse_int32_from_unsigned__.c
+++ b/libparsepcf_parse_int32_from_unsigned__.c
@@ -5,9 +5,8 @@
 int32_t
 libparsepcf_parse_int32_from_unsigned__(uint32_t u)
 {
-	if (u & UINT32_C(0x80000000)) {
+	if (u & UINT32_C(0x80000000))
 		return (int32_t)(uint32_t)~u - 1;
-	} else {
+	else
 		return (int32_t)u;
-	}
 }