From 1a2b0065fefa69fc4497be447c1e59c832a28521 Mon Sep 17 00:00:00 2001
From: Project Nayuki <me@nayuki.io>
Date: Sat, 6 May 2017 11:43:14 +0000
Subject: [PATCH] Updated comments in C code.

---
 c/qrcodegen.c | 20 +++++++++++++++-----
 c/qrcodegen.h | 14 +++++++-------
 2 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/c/qrcodegen.c b/c/qrcodegen.c
index b3e824b..08a9387 100644
--- a/c/qrcodegen.c
+++ b/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
-// they take input data only from arguments, return output data or store in pointer arguments,
-// perform no I/O (e.g. reading clock or writing to console), and don't read/write global variables.
-// Also, each of these functions allocate only a small constant amount of memory on the stack,
-// they don't allocate or free anything on the heap, and they are thread-safe.
+// Regarding all public and private functions defined in this source file:
+// - They require all pointer/array arguments to be not null.
+// - They only read input scalar/array arguments, write to output pointer/array
+//   arguments, and return scalar values; they are "pure" functions.
+// - 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,
diff --git a/c/qrcodegen.h b/c/qrcodegen.h
index a945b17..478d28c 100644
--- a/c/qrcodegen.h
+++ b/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
- * must have a length of at least qrcodegen_BUFFER_LEN_FOR_VERSION(version),
- * which equals ceil(size^2 / 8 + 1).
+ * The result is in the range [21, 177]. Note that the length of the array buffer
+ * is related to the side length - every 'uint8_t qrcode[]' must have length at least
+ * qrcodegen_BUFFER_LEN_FOR_VERSION(version), which equals ceil(size^2 / 8 + 1).
  */
 int qrcodegen_getSize(const uint8_t qrcode[]);