Updated comments in C code.

c/qrcodegen.c

@@ -37,11 +37,21 @@
 
 /*---- Forward declarations for private functions ----*/
 
-// Note: All public and private functions defined in this source file are "pure", in the sense that
+// Regarding all public and private functions defined in this source file:
-// they take input data only from arguments, return output data or store in pointer arguments,
+// - They require all pointer/array arguments to be not null.
-// perform no I/O (e.g. reading clock or writing to console), and don't read/write global variables.
+// - They only read input scalar/array arguments, write to output pointer/array
-// Also, each of these functions allocate only a small constant amount of memory on the stack,
+//   arguments, and return scalar values; they are "pure" functions.
-// they don't allocate or free anything on the heap, and they are thread-safe.
+// - They don't read mutable global variables or write to any global variables.
+// - They don't perform I/O, read the clock, print to console, etc.
+// - They allocate a small and constant amount of stack memory.
+// - They don't allocate or free any memory on the heap.
+// - They don't recurse or mutually recurse. All the code
+//   could be inlined into the top-level public functions.
+// - They run in at most quadratic time with respect to input arguments.
+//   Most functions run in linear time, and some in constant time.
+//   There are no unbounded loops or non-obvious termination conditions.
+// - They are completely thread-safe if the caller does not give the
+//   same writable buffer to concurrent calls to these functions.
 
 testable int getTextProperties(const char *text, bool *isNumeric, bool *isAlphanumeric, int *textBits);
 static int fitVersionToData(int minVersion, int maxVersion, enum qrcodegen_Ecc ecl,

c/qrcodegen.h

@@ -74,7 +74,7 @@ enum qrcodegen_Mask {
 
 
 
-/*---- Top-level QR Code functions ----*/
+/*---- Functions to generate QR Codes ----*/
 
 /* 
  * Encodes the given text string to a QR Code symbol, returning true if encoding succeeded.
@@ -92,7 +92,7 @@ enum qrcodegen_Mask {
  *   can hold any UTF-8 string up to 2953 bytes, or any alphanumeric string
  *   up to 4296 characters, or any digit string up to 7089 characters.
  *   These numbers represent the hard upper limit of the QR Code standard.
- * - Please consult the QR Code standard document for information on
+ * - Please consult the QR Code specification for information on
  *   data capacities per version, ECC level, and text encoding mode.
  */
 bool qrcodegen_encodeText(const char *text, uint8_t tempBuffer[], uint8_t qrcode[],
@@ -114,7 +114,7 @@ bool qrcodegen_encodeText(const char *text, uint8_t tempBuffer[], uint8_t qrcode
  * - If successful, the resulting QR Code will use byte mode to encode the data.
  * - In the most optimistic case, a QR Code at version 40 with low ECC can hold any byte
  *   sequence up to length 2953. This is the hard upper limit of the QR Code standard.
- * - Please consult the QR Code standard document for information on
+ * - Please consult the QR Code specification for information on
  *   data capacities per version, ECC level, and text encoding mode.
  */
 bool qrcodegen_encodeBinary(uint8_t dataAndTemp[], size_t dataLen, uint8_t qrcode[],
@@ -122,13 +122,13 @@ bool qrcodegen_encodeBinary(uint8_t dataAndTemp[], size_t dataLen, uint8_t qrcod
 
 
 
-/*---- Low-level QR Code functions ----*/
+/*---- Functions to extract raw data from QR Codes ----*/
 
 /* 
  * Returns the side length of the given QR Code, assuming that encoding succeeded.
- * The result is in the range [21, 177]. Note that every 'uint8_t qrcode[]' buffer
+ * The result is in the range [21, 177]. Note that the length of the array buffer
- * must have a length of at least qrcodegen_BUFFER_LEN_FOR_VERSION(version),
+ * is related to the side length - every 'uint8_t qrcode[]' must have length at least
- * which equals ceil(size^2 / 8 + 1).
+ * qrcodegen_BUFFER_LEN_FOR_VERSION(version), which equals ceil(size^2 / 8 + 1).
  */
 int qrcodegen_getSize(const uint8_t qrcode[]);