docs: description of Common and RawCode

src/klotski/raw_code/raw_code.h

@@ -1,5 +1,39 @@
 #pragma once
 
+/// RawCode is an uncompressed coding scheme, which is used for program calculation.
+/// It encodes a `5x4` chessboard as `0 ~ 19`, and uses 3-bits to represent each position,
+/// occupying a total of 60-bits, and stored in a `uint64_t` variable.
+///
+///   00 01 02 03
+///   04 05 06 07    fill  20-slots
+///   08 09 10 11    0000  (19) (18) (17) (16) ... (03) (02) (01) (00)
+///   12 13 14 15    (4b)  (60b)
+///   16 17 18 19
+///
+///   Eg1:
+///     % # # %    2x1 2x2 ... 2x1    010 100 111 010
+///     % # # %    ... ... ... ...    111 111 111 111
+///     @ $ $ @    2x1 1x2 ... 2x1    010 001 111 010
+///     @ & * @    ... 1x1 1x1 ...    111 011 011 111
+///     *     &    1x1 0x0 0x0 1x1    011 000 000 011
+///
+///            19  18  17  16  15  14  13  12  11  10  09  08  07  06  05  04  03  02  01  00
+///      0000 011 000 000 011 111 011 011 111 010 111 001 010 111 111 111 111 010 111 100 010
+///      0000  0110 0000 0011  1110 1101 1111  0101 1100 1010  1111 1111 1111  0101 1110 0010
+///         0     6    0    3     E    D    F     5    C    A     F    F    F     5    E    2
+///
+///   Eg2:
+///     * @ & %    1x1 1x1 1x1 2x1    011 011 011 010
+///     # # $ %    2x2 ... 2x1 ...    100 111 010 111
+///     # # $ ^    ... ... ... 2x1    111 111 111 010
+///       ~ ~ ^    0x0 1x2 ... ...    000 001 111 111
+///       @ % %    0x0 1x1 1x2 ...    000 011 001 111
+///
+///            19  18  17  16  15  14  13  12  11  10  09  08  07  06  05  04  03  02  01  00
+///      0000 111 001 011 000 111 111 001 000 010 111 111 111 111 010 111 100 010 011 011 011
+///      0000  1110 0101 1000  1111 1100 1000  0101 1111 1111  1110 1011 1100  0100 1101 1011
+///         0     E    5    8     F    C    8     5    F    F     E    B    C     4    D    B
+
 #include <string>
 #include <cstdint>
 #include <ostream>

src/klotski/utils/common.h

@@ -1,5 +1,16 @@
 #pragma once
 
+/// Klotski is an intellectual game, which fill a `5x4` chessboard with movable pieces
+/// (or called blocks), and a valid layout obeys the following three requirements:
+///
+///   1. There are four types of blocks, namely `2x2` `2x1` `1x2` `1x1`.
+///
+///   2. There should be at least two free slots (or called space).
+///
+///   3. `2x2` block must have and only one, `2x1` `1x2` `1x1` are not required in number.
+///
+/// After statistics, there are a total of 29334498 cases that meet the above requirements.
+
 #include <cstdint>
 
 /// 0b101 and 0b110 reserved
@@ -40,6 +51,10 @@
 #define F_2x1_R (uint64_t)0x38038 // 111 000 000 000 111 000
 #define F_1x2_D (uint64_t)0x3F000 // 111 111 000 000 000 000
 
+/// `range_reverse` flip a 32bit data every two bits
+///   00 01 10 11 ...  =>  ... 11 10 01 00
+///   (high 8-bits)           (low 8-bits)
+
 class Common {
 public:
     static uint32_t range_reverse(uint32_t bin);