doc (#490)

Author: notJoon

contract/p/gnoswap/uint256/bits_table.gno

@@ -1,11 +1,18 @@
 // Copyright 2017 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
-
-// Code generated by go run make_tables.go. DO NOT EDIT.
-
 package uint256
 
+// ntz8tab: A lookup table for 8-bit values (0-255) that shows
+// the number of trailing zeros (zeros from the rightmost/LSB position).
+//
+// Example) 0x28 (binary 00101000)
+//
+//	Binary: [ 0  0  1  0  1  0  0  0 ]
+//	                         ^^^^^^^^
+//                          3 consecutive zeros
+//
+//  ntz8tab[0x28] = 3
 const ntz8tab = "" +
 	"\x08\x00\x01\x00\x02\x00\x01\x00\x03\x00\x01\x00\x02\x00\x01\x00" +
 	"\x04\x00\x01\x00\x02\x00\x01\x00\x03\x00\x01\x00\x02\x00\x01\x00" +
@@ -24,6 +31,15 @@ const ntz8tab = "" +
 	"\x05\x00\x01\x00\x02\x00\x01\x00\x03\x00\x01\x00\x02\x00\x01\x00" +
 	"\x04\x00\x01\x00\x02\x00\x01\x00\x03\x00\x01\x00\x02\x00\x01\x00"
 
+// pop8tab: A lookup table for 8-bit values (0-255) that allows
+// quick lookup of the number of set bits (bits set to 1).
+//
+// Example) 0xB2 (binary 10110010)
+//
+//	Binary: [ 1  0  1  1  0  0  1  0 ]
+//	Total of 4 set bits
+//
+//  pop8tab[0xB2] = 4
 const pop8tab = "" +
 	"\x00\x01\x01\x02\x01\x02\x02\x03\x01\x02\x02\x03\x02\x03\x03\x04" +
 	"\x01\x02\x02\x03\x02\x03\x03\x04\x02\x03\x03\x04\x03\x04\x04\x05" +
@@ -42,6 +58,15 @@ const pop8tab = "" +
 	"\x03\x04\x04\x05\x04\x05\x05\x06\x04\x05\x05\x06\x05\x06\x06\x07" +
 	"\x04\x05\x05\x06\x05\x06\x06\x07\x05\x06\x06\x07\x06\x07\x07\x08"
 
+// rev8tab: A lookup table that pre-calculates bit-reversed results
+// for 8-bit values (0-255).
+//
+// Example) 0x16 (binary 00010110)
+//
+//	Binary:       [ 0  0  0  1  0  1  1  0 ]
+//	Reversed:     [ 0  1  1  0  1  0  0  0 ] -> 0x68 (104 in decimal)
+//
+//  rev8tab[0x16] = 0x68
 const rev8tab = "" +
 	"\x00\x80\x40\xc0\x20\xa0\x60\xe0\x10\x90\x50\xd0\x30\xb0\x70\xf0" +
 	"\x08\x88\x48\xc8\x28\xa8\x68\xe8\x18\x98\x58\xd8\x38\xb8\x78\xf8" +
@@ -60,6 +85,17 @@ const rev8tab = "" +
 	"\x07\x87\x47\xc7\x27\xa7\x67\xe7\x17\x97\x57\xd7\x37\xb7\x77\xf7" +
 	"\x0f\x8f\x4f\xcf\x2f\xaf\x6f\xef\x1f\x9f\x5f\xdf\x3f\xbf\x7f\xff"
 
+// len8tab: A lookup table that pre-calculates the "bit length"
+// of 8-bit values (0-255).
+// (Bit length: position of the most significant bit + 1)
+//
+// Examples)
+//
+//	0x00 (binary 00000000) → No MSB → length 0
+//	0x01 (binary 00000001) → MSB at rightmost position → length 1
+//	0x02 (binary 00000010) ~ 0x03 (00000011) → length 2
+//	0x04 (binary 00000100) ~ 0x07 (00000111) → length 3
+//	...
 const len8tab = "" +
 	"\x00\x01\x02\x02\x03\x03\x03\x03\x04\x04\x04\x04\x04\x04\x04\x04" +
 	"\x05\x05\x05\x05\x05\x05\x05\x05\x05\x05\x05\x05\x05\x05\x05\x05" +