h48

commit dc64668ceba09cd048fb92af77857b594c584c27
parent f148aa65dfe587e7b5d2f48b5005be670788dbe6
Author: Sebastiano Tronto <sebastiano@tronto.net>
Date:   Mon,  5 Aug 2024 17:40:15 +0200

Comment cube.h

Diffstat:
M
README.md
 | 
3
+++
M
TODO.txt
 | 
2
--
M
src/cube.h
 | 
28
++++++++++++++++++++++++----

3 files changed, 27 insertions(+), 6 deletions(-)
diff --git 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
@@ -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
@@ -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 *, ...));