Improved error messages and add some comments in nissy.h

1 files changed, 91 insertions, 29 deletions

diff --git a/src/nissy.h b/src/nissy.h
index 1fc1776..c78fb50 100644
--- a/src/nissy.h
+++ b/src/nissy.h
@@ -1,10 +1,17 @@
 /*
-If you include this file, you should also include the following:
+This is libnissy (temporarily also known as h48), a Rubik's cube library.
 
-inttypes, stdarg, stdbool, string
+If you include this file, you should also use the following includes:
 
-All the functions below return 0 in case of success and a positive
-number in case of error, unless otherwise specified.
+#include <inttypes>
+#include <stdarg>
+#include <stdbool>
+#include <string>
+
+All the functions below return 0 in case of success and a positive number
+in case of error, unless otherwise specified. Errors are checked in code
+order: for example if error code 1 is returned then it could that also
+an error with code 2 or higher occurred.
 
 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
@@ -18,40 +25,85 @@ A transformation must be given in the format
 for example 'rotation UF' or 'mirrored BL'.
 */
 
-/* Apply the secod argument as a permutation on the first argument */
+/*
+Apply the secod argument as a permutation on the first argument.
+
+Return values:
+   0    Valid result
+   1    The given cube is invalid
+   2    The given permutation is invalid
+   9    The resulting cube is not solvable
+*/
 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 */
+/*
+Compute the inverse of the given cube.
+
+Return values:
+   0    Valid result
+   1    The given cube is invalid
+   9    The resulting cube is not solvable
+*/
 int64_t nissy_inverse(
         const char cube[static 22],
         char result[static 22]
 );
 
-/* Apply the given sequence of moves on the given cube */
+/*
+Apply the given sequence of moves on the given cube.
+
+Return values:
+   0    Valid result
+   1    The given cube is invalid
+   8    The given moves are invalid
+   9    The resulting cube is not solvable
+*/
 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 */
+/*
+Apply the single given transformation to the given cube.
+
+Return values:
+   0    Valid result
+   1    The given cube is invalid
+   8    The given transformation is invalid
+   9    The resulting cube is not solvable
+*/
 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 */
+/*
+Apply the given moves to the solved cube.
+
+Return values:
+   0    Valid result
+   1    The given moves are invalid
+*/
 int64_t nissy_frommoves(
         const char *moves,
         char result[static 22]
 );
 
-/* Convert the given cube between the two given formats */
+/*
+Convert the given cube between the two given formats.
+
+Return values:
+   0    Valid result
+   1    The given cube or format_in is invalid
+   2    The resulting cube or format_out is invalid
+   3    The resulting cube is inconsistent
+*/
 int64_t nissy_convert(
         const char *format_in,
         const char *format_out,
@@ -70,40 +122,48 @@ int64_t nissy_getcube(
 );
 
 /*
-Returns the size of the data generated by nissy_gendata, when called with
-the same parameters, or -1 in case of error. The returned value can be
-slightly larger than the actual table size.
+Compute the size of the data generated by nissy_gendata, when called with
+the same parameters, or -1 in case of error.
+
+Return values:
+   -1   Error
+   >=0  The size of the table, in bytes
 */
 int64_t nissy_datasize(
         const char *solver
 );
 
-/* Returns the number of bytes written, or -1 in case of error */
+/*
+Compute the data for the given solver and store it in generated_data.
+
+Return values:
+   -1   Error
+   >=0  The size of the table, in bytes
+*/
 int64_t nissy_gendata(
         const char *solver,
         void *generated_data
 );
 
-/* Temporarily added to test h48 intermediate tables */
-int64_t nissy_derivedata(
-        const char *options,
-        const void *fulltable,
-        void *generated_data
-);
-
-/* Returns 0 on positive check, 1 on error */
-int64_t nissy_checkdata(
-        const char *solver,
-        const void *data
-);
+/*
+Print information on a data table via the provided callback writer.
 
-/* Print information on a data table via the provided callback writer */
+Return values:
+   0    No error
+   1    The given data could not be read correctly
+*/
 int64_t nissy_datainfo(
         const void *table,
         void (*write)(const char *, ...)
 );
 
-/* Returns the number of solutions found, or -1 in case of error */
+/*
+Solve the given cube using the given solver and options
+
+Return values:
+   -1   Error
+   >=0  The number of solutions found
+*/
 int64_t nissy_solve(
         const char cube[static 22],
         const char *solver, 
@@ -116,5 +176,7 @@ int64_t nissy_solve(
         char *solutions
 );
 
-/* Set a global logger function used by this library. */
+/*
+Set a global logger function used by this library.
+*/
 void nissy_setlogger(void (*logger_function)(const char *, ...));