Fix godoc comments

[tklauser]

Fix typos and some other issues in public facing godoc comments.

[github-actions]

$ make
go build ./...
go: downloading go.yaml.in/yaml/v3 v3.0.3
go: downloading github.com/cilium/hive v0.0.0-20250731144630-28e7a35ed227
go: downloading golang.org/x/time v0.5.0
go: downloading github.com/spf13/cobra v1.8.0
go: downloading github.com/spf13/pflag v1.0.5
go: downloading github.com/cilium/stream v0.0.0-20240209152734-a0792b51812d
go: downloading github.com/liggitt/tabwriter v0.0.0-20181228230101-89fcab3d43de
go: downloading github.com/spf13/viper v1.18.2
go: downloading go.uber.org/dig v1.17.1
go: downloading golang.org/x/term v0.16.0
go: downloading github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc
go: downloading github.com/mitchellh/mapstructure v1.5.0
go: downloading golang.org/x/sys v0.17.0
go: downloading golang.org/x/tools v0.17.0
go: downloading github.com/spf13/cast v1.6.0
go: downloading github.com/fsnotify/fsnotify v1.7.0
go: downloading github.com/sagikazarmark/slog-shim v0.1.0
go: downloading github.com/spf13/afero v1.11.0
go: downloading golang.org/x/text v0.14.0
go: downloading github.com/subosito/gotenv v1.6.0
go: downloading github.com/hashicorp/hcl v1.0.0
go: downloading gopkg.in/ini.v1 v1.67.0
go: downloading github.com/magiconair/properties v1.8.7
go: downloading github.com/pelletier/go-toml/v2 v2.1.0
go: downloading gopkg.in/yaml.v3 v3.0.1
STATEDB_VALIDATE=1 go test ./... -cover -vet=all -test.count 1
go: downloading github.com/stretchr/testify v1.8.4
go: downloading go.uber.org/goleak v1.3.0
go: downloading golang.org/x/exp v0.0.0-20240119083558-1b970713d09a
go: downloading github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2
ok  	github.com/cilium/statedb	407.307s	coverage: 78.6% of statements
ok  	github.com/cilium/statedb/index	0.005s	coverage: 33.7% of statements
ok  	github.com/cilium/statedb/internal	0.024s	coverage: 42.9% of statements
ok  	github.com/cilium/statedb/lpm	3.984s	coverage: 77.6% of statements
ok  	github.com/cilium/statedb/part	61.530s	coverage: 87.2% of statements
ok  	github.com/cilium/statedb/reconciler	0.291s	coverage: 91.9% of statements
	github.com/cilium/statedb/reconciler/benchmark		coverage: 0.0% of statements
	github.com/cilium/statedb/reconciler/example		coverage: 0.0% of statements
go test -race ./... -test.count 1
ok  	github.com/cilium/statedb	38.887s
ok  	github.com/cilium/statedb/index	1.015s
ok  	github.com/cilium/statedb/internal	1.027s
ok  	github.com/cilium/statedb/lpm	2.811s
ok  	github.com/cilium/statedb/part	35.548s
ok  	github.com/cilium/statedb/reconciler	1.322s
?   	github.com/cilium/statedb/reconciler/benchmark	[no test files]
?   	github.com/cilium/statedb/reconciler/example	[no test files]
go test ./... -bench . -benchmem -test.run xxx
goos: linux
goarch: amd64
pkg: github.com/cilium/statedb
cpu: AMD EPYC 9V74 80-Core Processor                
BenchmarkDB_WriteTxn_1-4                      	  710559	      1624 ns/op	    615634 objects/sec	    1000 B/op	      16 allocs/op
BenchmarkDB_WriteTxn_10-4                     	 1674247	       641.1 ns/op	   1559759 objects/sec	     520 B/op	       8 allocs/op
BenchmarkDB_WriteTxn_100-4                    	 2129408	       563.0 ns/op	   1776171 objects/sec	     536 B/op	       7 allocs/op
BenchmarkDB_WriteTxn_1000-4                   	 1759744	       643.7 ns/op	   1553591 objects/sec	     522 B/op	       7 allocs/op
BenchmarkDB_WriteTxn_100_SecondaryIndex-4     	  785923	      1338 ns/op	    747472 objects/sec	    1100 B/op	      20 allocs/op
BenchmarkDB_WriteTxn_CommitOnly_100Tables-4   	  947731	      1140 ns/op	    1112 B/op	       5 allocs/op
BenchmarkDB_WriteTxn_CommitOnly_1Table-4      	 1634193	       731.1 ns/op	     224 B/op	       5 allocs/op
BenchmarkDB_NewWriteTxn-4                     	 1832095	       649.8 ns/op	     200 B/op	       4 allocs/op
BenchmarkDB_WriteTxnCommit100-4               	 1000000	      1106 ns/op	    1096 B/op	       5 allocs/op
BenchmarkDB_NewReadTxn-4                      	567605024	         2.121 ns/op	       0 B/op	       0 allocs/op
BenchmarkDB_Modify-4                          	    1654	    732510 ns/op	   1365169 objects/sec	  546078 B/op	    8094 allocs/op
BenchmarkDB_GetInsert-4                       	    1550	    773950 ns/op	   1292073 objects/sec	  530069 B/op	    8094 allocs/op
BenchmarkDB_RandomInsert-4                    	    1760	    667488 ns/op	   1498155 objects/sec	  522024 B/op	    7094 allocs/op
BenchmarkDB_RandomReplace-4                   	     417	   2832566 ns/op	    353037 objects/sec	 2073407 B/op	   29146 allocs/op
BenchmarkDB_SequentialInsert-4                	    1810	    642608 ns/op	   1556160 objects/sec	  522025 B/op	    7094 allocs/op
BenchmarkDB_SequentialInsert_Prefix-4         	     483	   2445452 ns/op	    408922 objects/sec	 3563334 B/op	   45542 allocs/op
BenchmarkDB_Changes_Baseline-4                	    1572	    760224 ns/op	   1315402 objects/sec	  582205 B/op	    9185 allocs/op
BenchmarkDB_Changes-4                         	     934	   1282666 ns/op	    779626 objects/sec	  783494 B/op	   12336 allocs/op
BenchmarkDB_RandomLookup-4                    	   25814	     46130 ns/op	  21678094 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_SequentialLookup-4                	   24802	     48606 ns/op	  20573565 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_Prefix_SecondaryIndex-4           	    7256	    150396 ns/op	   6649094 objects/sec	  124920 B/op	    1025 allocs/op
BenchmarkDB_FullIteration_All-4               	     829	   1435473 ns/op	  69663443 objects/sec	     104 B/op	       4 allocs/op
BenchmarkDB_FullIteration_Prefix-4            	     751	   1501750 ns/op	  66588999 objects/sec	     136 B/op	       5 allocs/op
BenchmarkDB_FullIteration_Get-4               	     169	   7268692 ns/op	  13757633 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_FullIteration_Get_Secondary-4     	      94	  12467543 ns/op	   8020827 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_FullIteration_ReadTxnGet-4        	     187	   6421840 ns/op	  15571860 objects/sec	       0 B/op	       0 allocs/op
BenchmarkDB_PropagationDelay-4                	  707570	      1647 ns/op	        13.00 50th_µs	        17.00 90th_µs	        75.00 99th_µs	    1121 B/op	      19 allocs/op
BenchmarkDB_WriteTxn_100_LPMIndex-4           	  498438	      2365 ns/op	    422795 objects/sec	    1825 B/op	      37 allocs/op
BenchmarkDB_WriteTxn_1_LPMIndex-4             	  136554	     14598 ns/op	     68501 objects/sec	   15818 B/op	      81 allocs/op
BenchmarkDB_LPMIndex_Get-4                    	     360	   3292815 ns/op	   3036915 objects/sec	       0 B/op	       0 allocs/op
BenchmarkWatchSet_4-4                         	 2372288	       502.3 ns/op	     296 B/op	       4 allocs/op
BenchmarkWatchSet_16-4                        	  762124	      1539 ns/op	    1096 B/op	       5 allocs/op
BenchmarkWatchSet_128-4                       	   85561	     13922 ns/op	    8904 B/op	       5 allocs/op
BenchmarkWatchSet_1024-4                      	    7910	    140899 ns/op	   73744 B/op	       5 allocs/op
PASS
ok  	github.com/cilium/statedb	43.409s
PASS
ok  	github.com/cilium/statedb/index	0.004s
goos: linux
goarch: amd64
pkg: github.com/cilium/statedb/internal
cpu: AMD EPYC 9V74 80-Core Processor                
Benchmark_SortableMutex-4   	 5794650	       207.0 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/cilium/statedb/internal	1.205s
goos: linux
goarch: amd64
pkg: github.com/cilium/statedb/lpm
cpu: AMD EPYC 9V74 80-Core Processor                
Benchmark_txn_insert/batchSize=1-4         	    1773	    605563 ns/op	   1651355 objects/sec	  838407 B/op	   13975 allocs/op
Benchmark_txn_insert/batchSize=10-4        	    2728	    371092 ns/op	   2694750 objects/sec	  385193 B/op	    6668 allocs/op
Benchmark_txn_insert/batchSize=100-4       	    3457	    339707 ns/op	   2943711 objects/sec	  345615 B/op	    6027 allocs/op
Benchmark_txn_delete/batchSize=1-4         	    1572	    759355 ns/op	   1316907 objects/sec	 1286470 B/op	   13976 allocs/op
Benchmark_txn_delete/batchSize=10-4        	    3261	    371639 ns/op	   2690783 objects/sec	  372417 B/op	    5769 allocs/op
Benchmark_txn_delete/batchSize=100-4       	    3676	    329263 ns/op	   3037084 objects/sec	  286753 B/op	    5038 allocs/op
Benchmark_LPM_Lookup-4                     	    7761	    154341 ns/op	   6479145 objects/sec	       0 B/op	       0 allocs/op
Benchmark_LPM_All-4                        	  133941	      8943 ns/op	 111815904 objects/sec	      32 B/op	       1 allocs/op
Benchmark_LPM_Prefix-4                     	  131067	      9143 ns/op	 109378680 objects/sec	      32 B/op	       1 allocs/op
Benchmark_LPM_LowerBound-4                 	  240904	      4823 ns/op	 103675967 objects/sec	     288 B/op	       2 allocs/op
PASS
ok  	github.com/cilium/statedb/lpm	11.645s
goos: linux
goarch: amd64
pkg: github.com/cilium/statedb/part
cpu: AMD EPYC 9V74 80-Core Processor                
Benchmark_Uint64Map_Random-4                  	    1521	    741047 ns/op	   1349443 items/sec	 2527096 B/op	    6040 allocs/op
Benchmark_Uint64Map_Sequential-4              	    1873	    625270 ns/op	   1599309 items/sec	 2216725 B/op	    5754 allocs/op
Benchmark_Uint64Map_Sequential_Insert-4       	    2146	    572138 ns/op	   1747830 items/sec	 2208720 B/op	    4753 allocs/op
Benchmark_Uint64Map_Sequential_Txn_Insert-4   	   12160	     98807 ns/op	  10120725 items/sec	   86352 B/op	    2028 allocs/op
Benchmark_Uint64Map_Random_Insert-4           	    1770	    707448 ns/op	   1413531 items/sec	 2520500 B/op	    5043 allocs/op
Benchmark_Uint64Map_Random_Txn_Insert-4       	    6657	    163277 ns/op	   6124574 items/sec	  117375 B/op	    2399 allocs/op
Benchmark_Insert_RootOnlyWatch-4              	   10000	    106595 ns/op	   9381293 objects/sec	   71504 B/op	    2033 allocs/op
Benchmark_Insert-4                            	    8328	    143880 ns/op	   6950226 objects/sec	  186937 B/op	    3060 allocs/op
Benchmark_Modify-4                            	   12862	     93200 ns/op	  10729648 objects/sec	   58224 B/op	    1007 allocs/op
Benchmark_GetInsert-4                         	   10000	    117823 ns/op	   8487319 objects/sec	   58224 B/op	    1007 allocs/op
Benchmark_Replace-4                           	33296382	        36.07 ns/op	  27721786 objects/sec	       0 B/op	       0 allocs/op
Benchmark_Replace_RootOnlyWatch-4             	33769646	        36.07 ns/op	  27726983 objects/sec	       0 B/op	       0 allocs/op
Benchmark_txn_1-4                             	 5650077	       210.8 ns/op	   4743064 objects/sec	     168 B/op	       3 allocs/op
Benchmark_txn_10-4                            	10651747	       111.1 ns/op	   8998389 objects/sec	      86 B/op	       2 allocs/op
Benchmark_txn_100-4                           	12753627	        91.97 ns/op	  10873569 objects/sec	      80 B/op	       2 allocs/op
Benchmark_txn_1000-4                          	11412690	       104.5 ns/op	   9571452 objects/sec	      65 B/op	       2 allocs/op
Benchmark_txn_delete_1-4                      	 5070453	       236.6 ns/op	   4226190 objects/sec	     664 B/op	       4 allocs/op
Benchmark_txn_delete_10-4                     	12041436	        97.91 ns/op	  10213703 objects/sec	     106 B/op	       1 allocs/op
Benchmark_txn_delete_100-4                    	13397931	        87.96 ns/op	  11369067 objects/sec	      47 B/op	       1 allocs/op
Benchmark_txn_delete_1000-4                   	15355832	        78.36 ns/op	  12762049 objects/sec	      24 B/op	       1 allocs/op
Benchmark_Get-4                               	   45535	     26360 ns/op	  37936765 objects/sec	       0 B/op	       0 allocs/op
Benchmark_All-4                               	  137467	      8607 ns/op	 116189994 objects/sec	       0 B/op	       0 allocs/op
Benchmark_Iterator_All-4                      	  145808	      8218 ns/op	 121680685 objects/sec	       0 B/op	       0 allocs/op
Benchmark_Iterator_Next-4                     	  162664	      7575 ns/op	 132010508 objects/sec	     896 B/op	       1 allocs/op
Benchmark_Hashmap_Insert-4                    	   17409	     68848 ns/op	  14524793 objects/sec	   74264 B/op	      20 allocs/op
Benchmark_Hashmap_Get_Uint64-4                	  153912	      7794 ns/op	 128299728 objects/sec	       0 B/op	       0 allocs/op
Benchmark_Hashmap_Get_Bytes-4                 	  125025	      9579 ns/op	 104395772 objects/sec	       0 B/op	       0 allocs/op
Benchmark_Delete_Random-4                     	      64	  17921632 ns/op	   5579849 objects/sec	 2111842 B/op	  102364 allocs/op
Benchmark_find16-4                            	242447319	         4.940 ns/op	       0 B/op	       0 allocs/op
Benchmark_findIndex16-4                       	100000000	        14.23 ns/op	       0 B/op	       0 allocs/op
Benchmark_find4-4                             	423444334	         2.840 ns/op	       0 B/op	       0 allocs/op
Benchmark_findIndex4-4                        	339799012	         3.527 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/cilium/statedb/part	39.519s
PASS
ok  	github.com/cilium/statedb/reconciler	0.005s
?   	github.com/cilium/statedb/reconciler/benchmark	[no test files]
?   	github.com/cilium/statedb/reconciler/example	[no test files]
go run ./reconciler/benchmark -quiet
1000000 objects reconciled in 1.91 seconds (batch size 1000)
Throughput 524657.33 objects per second
888MB total allocated, 6015180 in-use objects, 338MB bytes in use

[joamaki]

Thanks!