Comment cube.h

3 files changed, 27 insertions, 6 deletions

diff --git a/README.md b/README.md
index fb877f0..049c31d 100644
--- a/README.md
+++ b/README.md
@@ -227,3 +227,6 @@ The cube after the move F looks like this:
 ```
 MBODSFQH=ZBCYEFGHQTKL
 ```
+
+A cube in B32 format is always 21 characters long (22 if the terminating
+null character is included).
diff --git a/TODO.txt b/TODO.txt
index c4c49d8..68fe8a2 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -1,7 +1,5 @@
 # Documentation and cleanup
 
-- Add comments to cube.h
-  - one for each function?
 - Internal documentation
   - h48 solver and co
     - what is h and k
diff --git a/src/cube.h b/src/cube.h
index 28737c4..346b99a 100644
--- a/src/cube.h
+++ b/src/cube.h
@@ -1,39 +1,57 @@
-/* include: inttypes, stdarg, stdbool, string */
-
 /*
+If you include this file, you should also include the following:
+
+inttypes, stdarg, stdbool, string
+
 All the functions below return 0 in case of success and a positive
-number in case of error, unless otherwise specified. See (TODO:
-documentation) for details.
+number in case of error, unless otherwise specified.
+
+Arguments of type char [static 22] denote a cube in B32 format.
+Other available formats are H48 and SRC. See README.md for more info on
+these formats.
+
+Accepted moves are U, D, R, L, F and B, optionally followed by a 2,
+a ' or a 3.
+
+A transformation must be given in the format
+    (rotation|mirrored) (2 letters)
+for example 'rotation UF' or 'mirrored BL'.
 */
 
+/* Apply the secod argument as a permutation on the first argument */
 int64_t nissy_compose(
         const char cube[static 22],
         const char permutation[static 22],
         char result[static 22]
 );
 
+/* Compute the inverse of the given cube */
 int64_t nissy_inverse(
         const char cube[static 22],
         char result[static 22]
 );
 
+/* Apply the given sequence of moves on the given cube */
 int64_t nissy_applymoves(
         const char cube[static 22],
         const char *moves,
         char result[static 22]
 );
 
+/* Apply the single given transformation to the given cube */
 int64_t nissy_applytrans(
         const char cube[static 22],
         const char *transformation,
         char result[static 22]
 );
 
+/* Return the cube obtained by applying the given moves to the solved cube */
 int64_t nissy_frommoves(
         const char *moves,
         char result[static 22]
 );
 
+/* Convert the given cube between the two given formats */
 int64_t nissy_convert(
         const char *format_in,
         const char *format_out,
@@ -41,6 +59,7 @@ int64_t nissy_convert(
         char *result
 );
 
+/* Get the cube with the given ep, eo, cp and co values. */
 int64_t nissy_getcube(
         int64_t ep,
         int64_t eo,
@@ -81,4 +100,5 @@ int64_t nissy_solve(
         char *solutions
 );
 
+/* Set a global logger function used by this library. */
 void nissy_setlogger(void (*logger_function)(const char *, ...));