docs: adding skeleton README.md files for all vlib modules (#13034)

vlib/README.md

@@ -0,0 +1 @@
+# Documentation for all included modules...

vlib/arrays/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`arrays` provides some generic functions for processing arrays.
+

vlib/benchmark/README.md

@@ -1,4 +1,10 @@
-Example usage of this module:
+## Description:
+
+`benchmark` provides an easy way to measure how fast a piece of code is,
+and produce a readable report about it.
+
+## Example usage of this module:
+
 ```v
 import benchmark
 

vlib/bitfield/README.md

@@ -1,8 +1,7 @@
-# Quickstart
+## Description:
 
-`bitfield` is a module for
-manipulating arrays of bits, i.e. series of zeroes and ones spread across an
-array of storage units (unsigned 32-bit integers).
+`bitfield` is a module for manipulating arrays of bits, i.e. series of zeroes
+and ones spread across an array of storage units (unsigned 32-bit integers).
 
 ## BitField structure
 

vlib/builtin/README.md

@@ -0,0 +1,7 @@
+## Description:
+
+`builtin` is a module that is implicitly imported by every V program.
+It implements the builtin V types `array`, `string`, `map`.
+It also implements builtin functions like `println`, `eprintln`, `malloc`,
+`panic`, `print_backtrace`.
+

vlib/cli/README.md

@@ -1,3 +1,11 @@
+## Description:
+
+`cli` is a command line option parser, that supports
+declarative subcommands, each having separate set of options.
+
+See also the `flag` module, for a simpler command line option parser,
+that supports only options.
+
 Usage example:
 
 ```v

vlib/clipboard/README.md

@@ -0,0 +1,5 @@
+## Description:
+
+`clipboard` provides access to the platform's clipboard mechanism.
+You can use it to read from the system clipboard, and write to it
+from your applications.

vlib/compress/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`compress` is a namespace for (multiple) compression algorithms supported by V.
+At the moment, only `compress.zlib` is implemented.

vlib/compress/zlib/README.md

@@ -0,0 +1,16 @@
+## Description:
+
+`compress.zlib` implements zlib compression and decompression of binary data.
+
+## Examples:
+
+```v
+import compress.zlib
+
+fn main() {
+	uncompressed := 'Hello world!'
+	compressed := zlib.compress(uncompressed.bytes()) ?
+	decompressed := zlib.decompress(compressed) ?
+	assert decompressed == uncompressed.bytes()
+}
+```

vlib/crypto/README.md

@@ -0,0 +1,5 @@
+## Description:
+
+`crypto` is a namespace for multiple crypto algorithms.
+
+The implementations here are loosely based on [Go's crypto package](https://pkg.go.dev/crypto).

vlib/darwin/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`darwin` is a deprecated module that will be removed soon.
+Do not rely on it.

vlib/dl/README.md

@@ -0,0 +1,6 @@
+## Description:
+
+`dl` can be used to Dynamically Load a library during runtime.
+It is a thin wrapper over `LoadLibrary` on Windows, and `dlopen` on Unix.
+
+Using it, you can implement a plugin system for your application.

vlib/dl/dl.v

@@ -1,9 +1,8 @@
 module dl
 
-pub const (
-	version = 1
-	dl_ext  = get_shared_library_extension()
-)
+pub const version = 1
+
+pub const dl_ext = get_shared_library_extension()
 
 // get_shared_library_extension returns the platform dependent shared library extension
 // i.e. .dll on windows, .so on most unixes, .dylib on macos.

vlib/dl/dl_nix.c.v

@@ -6,10 +6,9 @@ $if linux {
 	#flag -ldl
 }
 
-pub const (
-	rtld_now  = C.RTLD_NOW
-	rtld_lazy = C.RTLD_LAZY
-)
+pub const rtld_now = C.RTLD_NOW
+
+pub const rtld_lazy = C.RTLD_LAZY
 
 fn C.dlopen(filename &char, flags int) voidptr
 

vlib/dl/dl_windows.c.v

@@ -1,9 +1,8 @@
 module dl
 
-pub const (
-	rtld_now  = 0
-	rtld_lazy = 0
-)
+pub const rtld_now = 0
+
+pub const rtld_lazy = 0
 
 fn C.LoadLibrary(libfilename &u16) voidptr
 

vlib/encoding/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`encoding` is a namespace for different formats/protocols encoding/decoding,
+like `csv`, `utf8`, `base64` etc.

vlib/flag/README.md

@@ -1,10 +1,17 @@
-The `flag` module helps command-line flag parsing.
-Main features are:
+## Description:
+
+The `flag` module is a command line option parser.
+Its main features are:
+- simplicity of usage.
 - parses flags like `-f` or '--flag' or '--stuff=things' or '--things stuff'.
 - handles bool, int, float and string args.
-- can print usage information listing all the declrared flags.
+- can print usage information listing all the declared flags.
 - handles unknown arguments as error.
 
+See also the `cli` module, for a more complex command line option parser,
+that supports declaring multiple subcommands each having a separate set of
+options.
+
 Usage example:
 
 ```v

vlib/fontstash/README.md

@@ -0,0 +1,5 @@
+## Description:
+
+`fontstash` is a thin wrapper over <https://github.com/memononen/fontstash>,
+which in turn is a light-weight online font texture atlas builder written in C.
+It uses stb_truetype to render fonts on demand to a texture atlas

vlib/gg/README.md

@@ -0,0 +1,35 @@
+## Description:
+
+`gg` is V's simple graphics module.
+It is currently implemented using `sokol`, and makes easy creating
+apps that just need a way to draw simple 2D shapes, and to react to
+user's keyboard/mouse input.
+
+## Example:
+
+```v
+module main
+
+import gg
+import gx
+
+fn main() {
+	mut context := gg.new_context(
+		bg_color: gx.rgb(174, 198, 255)
+		width: 600
+		height: 400
+		window_title: 'Polygons'
+		frame_fn: frame
+	)
+	context.run()
+}
+
+fn frame(mut ctx gg.Context) {
+	ctx.begin()
+	ctx.draw_convex_poly([f32(100.0), 100.0, 200.0, 100.0, 300.0, 200.0, 200.0, 300.0, 100.0, 300.0],
+		gx.blue)
+	ctx.draw_poly_empty([f32(50.0), 50.0, 70.0, 60.0, 90.0, 80.0, 70.0, 110.0], gx.black)
+	ctx.draw_triangle_filled(450, 142, 530, 280, 370, 280, gx.red)
+	ctx.end()
+}
+```

vlib/gx/README.md

@@ -0,0 +1,6 @@
+## Description:
+
+`gx` is a complementary module to `gg`, that just provides
+some predefined graphical color names/operations.
+
+NB: `gx` is going to be merged with `gg` soon.

vlib/hash/README.md

@@ -0,0 +1,7 @@
+## Description:
+
+`hash` provides a way to hash binary data, i.e. produce a shorter value,
+that is highly content dependent, so even slightly different content will
+produce widely different hashes.
+
+Hash functions are useful for implementing maps, caches etc.

vlib/io/README.md

@@ -0,0 +1,3 @@
+## Description:
+
+`io` provides common interfaces for buffered reading/writing of data.

vlib/js/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`js`  is frontend/browser specific module, that provides access to global JS functions.
+NB: it *only* works with the JS backend.

vlib/jsdom/README.md

@@ -0,0 +1,8 @@
+## Description:
+
+`jsdom` is frontend/browser specific module, that provides access to the DOM.
+NB: it *only* works with the JS backend.
+
+## Examples:
+Run `v -b js_browser examples/js_dom_draw/draw.js.v`,
+then open `examples/js_dom_draw/index.html` in your browser.

vlib/json/README.md

@@ -0,0 +1,36 @@
+## Description:
+
+`json` provides encoding/decoding of V data structures to/from JSON.
+
+## Examples:
+
+```v
+import json
+
+enum JobTitle {
+	manager
+	executive
+	worker
+}
+
+struct Employee {
+	name   string
+	age    int
+	salary f32
+	title  JobTitle
+}
+
+fn main() {
+	x := Employee{'Peter', 28, 95000.5, .worker}
+	println(x)
+	//
+	s := json.encode(x)
+	println('Employee x: $s')
+	assert s == '{"name":"Peter","age":28,"salary":95000.5,"title":2}'
+	//
+	y := json.decode(Employee, s) ?
+	//
+	println(y)
+	assert y == x
+}
+```

vlib/log/README.md

@@ -0,0 +1,5 @@
+## Description:
+
+`log` provides your application logging services.
+You can log to file or to the console and use different
+logging levels, so that you are not overwhelmed by the logs.

vlib/math/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`math` provides commonly used mathematical functions for
+trigonometry, logarithms, etc.

vlib/net/README.md

@@ -0,0 +1,5 @@
+## Description:
+
+`net` provides networking functions. It is mostly a wrapper to BSD sockets,
+so you can listen on a port, connect to remote TCP/UDP services, and
+communicate with them.

vlib/os/README.md

@@ -0,0 +1,5 @@
+## Description:
+
+`os` provides common OS/platform independent functions for accessing
+command line arguments, reading/writing files, listing folders,
+handling processes etc.

vlib/pg/README.md

@@ -1,5 +1,10 @@
+## Description:
+
+`pg` is a wrapper for the PostgreSQL client library. It provides access
+to a PostgreSQL DB server.
+
 Before you can use this module, you must first have PostgreSQL installed on
-your system. To do this, find your OS and perform the actions listed. 
+your system. To do this, find your OS and perform the actions listed.
 
 **NOTE**: These instructions are meant only as a convenience. If your OS is not
 listed or you need extra help, [go here](https://www.postgresql.org/download/).

vlib/picoev/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`picoev` is a thin wrapper over [picoev](https://github.com/kazuho/picoev),
+which in turn is "A tiny, lightning fast event loop for network applications".

vlib/picohttpparser/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`picohttpparser` is a thin wrapper over [picohttpparser](https://github.com/h2o/picohttpparser),
+which in turn is "a tiny, primitive, fast HTTP request/response parser."

vlib/rand/README.md

@@ -1,4 +1,4 @@
-# Quickstart
+# Description
 
 The V `rand` module provides two main ways in which users can generate pseudorandom numbers:
 
@@ -29,27 +29,27 @@ For arrays, see `rand.util`.
 
 # General Background
 
-A PRNG is a Pseudo Random Number Generator. 
-Computers cannot generate truly random numbers without an external source of noise or entropy. 
-We can use algorithms to generate sequences of seemingly random numbers, 
-but their outputs will always be deterministic. 
+A PRNG is a Pseudo Random Number Generator.
+Computers cannot generate truly random numbers without an external source of noise or entropy.
+We can use algorithms to generate sequences of seemingly random numbers,
+but their outputs will always be deterministic.
 This is often useful for simulations that need the same starting seed.
 
-If you need truly random numbers that are going to be used for cryptography, 
+If you need truly random numbers that are going to be used for cryptography,
 use the `crypto.rand` module.
 
 # Guaranteed functions
 
-The following 21 functions are guaranteed to be supported by `rand` 
+The following 21 functions are guaranteed to be supported by `rand`
 as well as the individual PRNGs.
 
-- `seed(seed_data)` where `seed_data` is an array of `u32` values. 
-    Different generators require different number of bits as the initial seed. 
-    The smallest is 32-bits, required by `sys.SysRNG`. 
+- `seed(seed_data)` where `seed_data` is an array of `u32` values.
+    Different generators require different number of bits as the initial seed.
+    The smallest is 32-bits, required by `sys.SysRNG`.
     Most others require 64-bits or 2 `u32` values.
 - `u32()`, `u64()`, `int()`, `i64()`, `f32()`, `f64()`
 - `u32n(max)`, `u64n(max)`, `intn(max)`, `i64n(max)`, `f32n(max)`, `f64n(max)`
-- `u32_in_range(min, max)`, `u64_in_range(min, max)`, `int_in_range(min, max)`, 
+- `u32_in_range(min, max)`, `u64_in_range(min, max)`, `int_in_range(min, max)`,
     `i64_in_range(min, max)`, `f32_in_range(min, max)`, `f64_in_range(min, max)`
 - `int31()`, `int63()`
 
@@ -59,7 +59,7 @@ PRNG, you can can change the global RNG to do so.
 
 # Seeding Functions
 
-All the generators are time-seeded. 
+All the generators are time-seeded.
 The helper functions publicly available in `rand.seed` module are:
 
 1. `time_seed_array()` - returns a `[]u32` that can be directly plugged into the `seed()` functions.
@@ -69,8 +69,8 @@ The helper functions publicly available in `rand.seed` module are:
 # Caveats
 
 Note that the `sys.SysRNG` struct (in the C backend) uses `C.srand()` which sets the seed globally.
-Consequently, all instances of the RNG will be affected. 
-This problem does not arise for the other RNGs. 
+Consequently, all instances of the RNG will be affected.
+This problem does not arise for the other RNGs.
 A workaround (if you _must_ use the libc RNG) is to:
 
 1. Seed the first instance.
@@ -83,5 +83,5 @@ A workaround (if you _must_ use the libc RNG) is to:
 
 Please note that [math interval](https://en.wikipedia.org/wiki/Interval_(mathematics)#Including_or_excluding_endpoints) notation is used throughout
 the function documentation to denote what numbers ranges include.
-An example of `[0, max)` thus denotes a range with all posible values 
+An example of `[0, max)` thus denotes a range with all posible values
 between `0` and `max` **including** 0 but **excluding** `max`.

vlib/readline/README.md

@@ -1,4 +1,4 @@
-# Readline
+# Description
 
 The `readline` module lets you await and read user input
 from a terminal in an easy and structured manner.

vlib/regex/README.md

@@ -1,4 +1,8 @@
-# V RegEx (Regular expression) 1.0 alpha
+# Description
+`regex` is a small but powerful regular expression library,
+written in pure V.
+
+NB: `regex` is *not* PCRE compatible.
 
 [TOC]
 
@@ -9,13 +13,13 @@ are valid for all the `regex` module features:
 
 1. The matching stops at the end of the string, *not* at newline characters.
 
-2. The basic atomic elements of this regex engine are the tokens. 
+2. The basic atomic elements of this regex engine are the tokens.
 In a query string a simple character is a token.
 
 
 ## Differences with PCRE:
 
-NB: We must point out that the **V-Regex module is not PCRE compliant** and thus 
+NB: We must point out that the **V-Regex module is not PCRE compliant** and thus
 some behaviour will be different. This difference is due to the V philosophy,
 to have one way and keep it simple.
 
@@ -24,13 +28,13 @@ The main differences can be summarized in the following points:
 - The basic element **is the token not the sequence of symbols**, and the most
 simple token, is a single character.
 
-- `|` **the OR operator acts on tokens,** for example `abc|ebc` is not 
+- `|` **the OR operator acts on tokens,** for example `abc|ebc` is not
 `abc` OR `ebc`. Instead it is evaluated like `ab`, followed by `c OR e`,
 followed by `bc`, because the **token is the base element**,
 not the sequence of symbols.
 Note: **Two char classes with an `OR` in the middle is a syntax error.**
 
-- The **match operation stops at the end of the string**. It does *NOT* stop 
+- The **match operation stops at the end of the string**. It does *NOT* stop
 at new line characters.
 
 
@@ -54,7 +58,7 @@ This token is a simple single character like `a` or `b` etc.
 
 ### Char class (cc)
 
-The character classes match all the chars specified inside. Use square 
+The character classes match all the chars specified inside. Use square
 brackets `[ ]` to enclose them.
 
 The sequence of the chars in the character class, is evaluated with an OR op.
@@ -65,7 +69,7 @@ but it doesn't match `C` or `z`.
 Inside a cc, it is possible to specify a "range" of characters, for example
 `[ad-h]` is equivalent to writing `[adefgh]`.
 
-A cc can have different ranges at the same time, for example `[a-zA-z0-9]` 
+A cc can have different ranges at the same time, for example `[a-zA-z0-9]`
 matches all the latin lowercase, uppercase and numeric characters.
 
 It is possible to negate the meaning of a cc, using the caret char at the
@@ -80,13 +84,13 @@ It is possible to mix all the properties of the char class together.
 NB: In order to match the `-` (minus) char, it must be preceded by
     a backslash in the cc, for example `[\-_\d\a]` will match:
       `-` minus,
-      `_` underscore, 
+      `_` underscore,
       `\d` numeric chars,
 	  `\a` lower case chars.
 
 ### Meta-chars
 
-A meta-char is specified by a backslash, before a character. 
+A meta-char is specified by a backslash, before a character.
 For example `\w` is the meta-char `w`.
 
 A meta-char can match different types of characters.
@@ -130,7 +134,7 @@ The dot is a particular meta-char, that matches "any char".
 
 It is simpler to explain it with an example:
 
-Suppose you have `abccc ddeef` as a source string, that you want to parse 
+Suppose you have `abccc ddeef` as a source string, that you want to parse
 with a regex. The following table show the query strings and the result of
 parsing source string.
 
@@ -151,14 +155,14 @@ The token `|`, means a logic OR operation between two consecutive tokens,
 i.e. `a|b` matches a character that is `a` or `b`.
 
 The OR token can work in a "chained way": `a|(b)|cd ` means test first `a`,
-if the char is not `a`, then test the group `(b)`, and if the group doesn't 
+if the char is not `a`, then test the group `(b)`, and if the group doesn't
 match too, finally test the token `c`.
 
-NB: ** unlike in PCRE, the OR operation works at token level!** 
+NB: ** unlike in PCRE, the OR operation works at token level!**
 It doesn't work at concatenation level!
 NB2: **Two char classes with an `OR` in the middle is a syntax error.**
 
-That also means, that a query string like `abc|bde` is not equal to 
+That also means, that a query string like `abc|bde` is not equal to
 `(abc)|(bde)`, but instead to `ab(c|b)de.
 The OR operation works only for `c|b`, not at char concatenation level.
 
@@ -177,7 +181,7 @@ outer round brackets `(...)+`. This group has a quantifier `+`, that say to
 match its content *at least one time*.
 
 Then we have a simple char token `c`, and a second group `#1`: `(pa)+`.
-This group also tries to match the sequence `pa`, *at least one time*, 
+This group also tries to match the sequence `pa`, *at least one time*,
 as specified by the `+` quantifier.
 
 Then, we have another simple token `z` and another simple token ` ?`,
@@ -190,7 +194,7 @@ can match `cpaz cpapaz cpapapaz` .
 In this implementation the groups are "capture groups". This means that the
 last temporal result for each group, can be retrieved from the `RE` struct.
 
-The "capture groups" are stored as indexes in the field `groups`, 
+The "capture groups" are stored as indexes in the field `groups`,
 that is an `[]int` inside the `RE` struct.
 
 **example:**
@@ -263,14 +267,14 @@ fn convert_html_rgb(in_col string) u32 {
 }
 ```
 
-Others utility functions are `get_group_by_id` and `get_group_bounds_by_id` 
+Others utility functions are `get_group_by_id` and `get_group_bounds_by_id`
 that get  directly the string of a group using its `id`:
 
 ```v ignore
 txt := "my used string...."
 for g_index := 0; g_index < re.group_count ; g_index++ {
 	println("#${g_index} [${re.get_group_by_id(txt, g_index)}] \
-    	bounds: ${re.get_group_bounds_by_id(g_index)}") 
+    	bounds: ${re.get_group_bounds_by_id(g_index)}")
 }
 ```
 
@@ -294,8 +298,8 @@ The `.group_csave` array will be filled then, following this logic:
 `re.group_csave[1+n*3]` - start index in the source string of the saved group
 `re.group_csave[1+n*3]` - end index in the source string of the saved group
 
-The regex will save groups, until it finishes, or finds that the array has no 
-more space. If the space ends, no error is raised, and further records will 
+The regex will save groups, until it finishes, or finds that the array has no
+more space. If the space ends, no error is raised, and further records will
 not be saved.
 
 ```v ignore
@@ -355,11 +359,11 @@ This regex module supports partially the question mark `?` PCRE syntax for group
 
 `(?:abcd)` **non capturing group**:  the content of the group will not be saved.
 
-`(?P<mygroup>abcdef)` **named group:** the group content is saved and labeled 
+`(?P<mygroup>abcdef)` **named group:** the group content is saved and labeled
 as `mygroup`.
 
-The label of the groups is saved in the `group_map` of the `RE` struct, 
-that is a map from `string` to `int`, where the value is the index in 
+The label of the groups is saved in the `group_map` of the `RE` struct,
+that is a map from `string` to `int`, where the value is the index in
 `group_csave` list of indexes.
 
 Here is an example for how to use them:
@@ -447,7 +451,7 @@ These functions are helpers to query the captured groups
 
 ```v ignore
 // get_group_bounds_by_name get a group boundaries by its name
-pub fn (re RE) get_group_bounds_by_name(group_name string) (int, int) 
+pub fn (re RE) get_group_bounds_by_name(group_name string) (int, int)
 
 // get_group_by_name get a group string by its name
 pub fn (re RE) get_group_by_name(group_name string) string
@@ -481,15 +485,15 @@ re.flag = regex.f_bin
 
 - `f_bin`: parse a string as bytes, utf-8 management disabled.
 
-- `f_efm`: exit on the first char matches in the query, used by the 
+- `f_efm`: exit on the first char matches in the query, used by the
            find function.
-	
+
 - `f_ms`:  matches only if the index of the start match is 0,
            same as `^` at the start of the query string.
-	
+
 - `f_me`:  matches only if the end index of the match is the last char
            of the input string, same as `$` end of query string.
-	
+
 - `f_nl`:  stop the matching if found a new line char `\n` or `\r`
 
 ## Functions
@@ -561,7 +565,7 @@ There are the following find  and replace functions:
 pub fn (re mut RE) find(in_txt string) (int,int)
 
 // find_all find all the "non overlapping" occurrences of the matching pattern
-// return a list of start end indexes like: [3,4,6,8] 
+// return a list of start end indexes like: [3,4,6,8]
 // the matches are [3,4] and [6,8]
 pub fn (re mut RE) find_all(in_txt string) []int
 
@@ -574,7 +578,7 @@ pub fn (mut re RE) find_all_str(in_txt string) []string
 #### Replace functions
 
 ```v ignore
-// replace return a string where the matches are replaced with the repl_str string, 
+// replace return a string where the matches are replaced with the repl_str string,
 // this function support groups in the replace string
 pub fn (re mut RE) replace(in_txt string, repl string) string
 ```
@@ -617,7 +621,7 @@ pub fn (mut re RE) replace_n(in_txt string, repl_str string, count int) string
 #### Custom replace function
 
 For complex find and replace operations, you can use `replace_by_fn` .
-The `replace_by_fn`, uses a custom replace callback function, thus 
+The `replace_by_fn`, uses a custom replace callback function, thus
 allowing customizations. The custom callback function is called for
 every non overlapped find.
 
@@ -629,7 +633,7 @@ The custom callback function must be of the type:
 // start   index of the start of the match in in_txt
 // end     index of the end   of the match in in_txt
 // --- the match is in in_txt[start..end] ---
-fn (re RE, in_txt string, start int, end int) string 
+fn (re RE, in_txt string, start int, end int) string
 ```
 
 The following example will clarify its usage:
@@ -642,7 +646,7 @@ fn my_repl(re regex.RE, in_txt string, start int, end int) string {
     g0 := re.get_group_by_id(in_txt, 0)
     g1 := re.get_group_by_id(in_txt, 1)
     g2 := re.get_group_by_id(in_txt, 2)
-    return "*$g0*$g1*$g2*"    
+    return "*$g0*$g1*$g2*"
 }
 
 fn main(){
@@ -650,7 +654,7 @@ fn main(){
     query := r"(.)(\A\w+)(.)"
 
     mut re := regex.regex_opt(query) or { panic(err) }
-   
+
     result := re.replace_by_fn(txt, my_repl)
     println(result)
 }
@@ -803,13 +807,13 @@ fn main(){
     query := r"(?P<format>https?)|(?P<format>ftps?)://(?P<token>[\w_]+.)+"
 
     mut re := regex.regex_opt(query) or { panic(err) }
-   
+
     start, end := re.match_string(txt)
     if start >= 0 {
         println("Match ($start, $end) => [${txt[start..end]}]")
         for g_index := 0; g_index < re.group_count ; g_index++ {
             println("#${g_index} [${re.get_group_by_id(txt, g_index)}] \
-            bounds: ${re.get_group_bounds_by_id(g_index)}")  
+            bounds: ${re.get_group_bounds_by_id(g_index)}")
         }
         for name in re.group_map.keys() {
             println("group:'$name' \t=> [${re.get_group_by_name(txt, name)}] \
@@ -831,17 +835,17 @@ fn main(){
     // init regex
     mut re := regex.RE{}
 	// max program length, can not be longer then the query
-    re.prog = []regex.Token    {len: query.len + 1} 
+    re.prog = []regex.Token    {len: query.len + 1}
 	// can not be more char class the the length of the query
-    re.cc   = []regex.CharClass{len: query.len}     
+    re.cc   = []regex.CharClass{len: query.len}
     re.prog = []regex.Token    {len: query.len+1}
 	// enable continuos group saving
-    re.group_csave_flag = true         
+    re.group_csave_flag = true
 	// set max 128 group nested
-    re.group_max_nested = 128          
-	// we can't have more groups than the half of the query legth 
-    re.group_max        = query.len>>1 
-    
+    re.group_max_nested = 128
+	// we can't have more groups than the half of the query legth
+    re.group_max        = query.len>>1
+
     // compile the query
     re.compile_opt(query) or { panic(err) }
 
@@ -870,7 +874,7 @@ fn main(){
         println("Match ($start, $end) => [${txt[start..end]}]")
         for g_index := 0; g_index < re.group_count ; g_index++ {
             println("#${g_index} [${re.get_group_by_id(txt, g_index)}] \
-            bounds: ${re.get_group_bounds_by_id(g_index)}")  
+            bounds: ${re.get_group_bounds_by_id(g_index)}")
         }
         for name in re.group_map.keys() {
             println("group:'$name' \t=> [${re.get_group_by_name(txt, name)}] \

vlib/runtime/README.md

@@ -0,0 +1,7 @@
+## Description:
+
+`runtime` provides access to functions describing the current platform:
+- whether it is 32bit or 64bit
+- how many CPUs/cores are available
+- whether the platform is little endian or big endian
+- etc.

vlib/semver/README.md

@@ -1,37 +1,37 @@
-# semver
-
-A library for working with versions in [semver][semver] format.
-
-## Usage
-
-```v
-import semver
-
-fn main() {
-	ver1 := semver.from('1.2.4') or {
-		println('Invalid version')
-		return
-	}
-	ver2 := semver.from('2.3.4') or {
-		println('Invalid version')
-		return
-	}
-	println(ver1.gt(ver2))
-	println(ver2.gt(ver1))
-	println(ver1.satisfies('>=1.1.0 <2.0.0'))
-	println(ver2.satisfies('>=1.1.0 <2.0.0'))
-	println(ver2.satisfies('>=1.1.0 <2.0.0 || >2.2.0'))
-}
-```
-
-```
-false
-true
-true
-false
-true
-```
-
-For more details see `semver.v` file.
-
-[semver]: https://semver.org/
+## Description:
+
+`semver` is a library for processing versions, that use the [semver][semver] format.
+
+## Examples:
+
+```v
+import semver
+
+fn main() {
+	ver1 := semver.from('1.2.4') or {
+		println('Invalid version')
+		return
+	}
+	ver2 := semver.from('2.3.4') or {
+		println('Invalid version')
+		return
+	}
+	println(ver1.gt(ver2))
+	println(ver2.gt(ver1))
+	println(ver1.satisfies('>=1.1.0 <2.0.0'))
+	println(ver2.satisfies('>=1.1.0 <2.0.0'))
+	println(ver2.satisfies('>=1.1.0 <2.0.0 || >2.2.0'))
+}
+```
+
+```
+false
+true
+true
+false
+true
+```
+
+For more details see `semver.v` file.
+
+[semver]: https://semver.org/

vlib/sokol/README.md

@@ -0,0 +1,6 @@
+## Description:
+
+`sokol` is a thin wrapper around [sokol](https://github.com/floooh/sokol),
+which in turn is a library of "Simple STB-style cross-platform libraries
+for C and C++, written in C.", that provide access to graphics/audio/input
+processing.

vlib/sqlite/README.md

@@ -1,5 +1,14 @@
+## Description:
+
+`sqlite` is a thin wrapper for [the SQLite library](https://sqlite.org/), which in turn is
+"a C-language library that implements a small, fast, self-contained,
+high-reliability, full-featured, SQL database engine."
+
 # Install SQLite Dependency
 
+Before you can use this module, you must first have the SQLite development
+library installed on your system.
+
 **Fedora 31**:
 
 `sudo dnf -y install sqlite-devel`

vlib/stbi/README.md

@@ -0,0 +1,4 @@
+## Description:
+
+`stbi` is a thin wrapper around [stb](https://github.com/nothings/stb)'s stb_image.h, which in turn
+is "a public domain image loader" for popular graphics image file formats.

vlib/strconv/README.md

@@ -0,0 +1,3 @@
+## Description:
+
+`strconv` provides functions for converting strings to numbers and numbers to strings.

vlib/strings/README.md

@@ -0,0 +1,3 @@
+## Description:
+
+`strings` provides utilities for efficiently processing large strings.

vlib/sync/README.md

@@ -0,0 +1,3 @@
+## Description:
+
+`sync` provides cross platform handling of concurrency primitives.

vlib/szip/README.md

@@ -0,0 +1,9 @@
+## Description:
+
+`szip` is a thin wrapper around [miniz.h](https://github.com/richgel999/miniz),
+which in turn is "Single C source file zlib-replacement library,
+originally from code.google.com/p/miniz".
+It provides utility functions for reading/writing .zip files.
+
+*TODO*
+Merge/move under vlib/compress/zip .

vlib/term/README.md

@@ -1,11 +1,11 @@
-# Quickstart
+## Description
 
-The V `term` module is a module designed to provide the building blocks
-for building very simple TUI apps.
-For more complex apps, you should really look at the `term.input` module,
-as it includes terminal events, is easier to use and is much more performant for large draws.
+The `term` module is designed to provide the building blocks for building
+very simple TUI apps. For more complex apps, you should really look at the
+`term.input` module, as it includes terminal events, is easier to use and
+is much more performant for large draws.
 
-# Use
+## Usage
 
 You can use the `term` module to either color the output on a terminal
 or to decide on where to put the output in your terminal.
@@ -39,7 +39,7 @@ fn main() {
 
 This simple program covers many of the principal aspects of the `term ` module.
 
-# API
+## API
 
 Here are some functions you should be aware of in the `term `module:
 

vlib/time/README.md

@@ -0,0 +1,17 @@
+## Description:
+
+`time` provides utilities for working with time and dates:
+- parsing of time values expressed in one of the commonly used standard time/date formats
+- formatting of time values
+- arithmetic over times/durations
+- converting between local time and UTC (timezone support)
+- stop watches for accurately measuring time durations
+- sleeping for a period of time
+
+## Examples:
+
+```v
+import time
+
+println(time.now())
+```

vlib/toml/README.md

@@ -1,4 +1,4 @@
-# TOML module
+## Description
 `toml` is a fully fledged [TOML v1.0.0](https://toml.io/en/v1.0.0) compatible parser written in pure V.
 The module is tested against the [official compliance tests](https://github.com/toml-lang/compliance).
 

vlib/v/README.md

@@ -1,3 +1,12 @@
+## Description
+
+`v` is a namespace for all of the V compiler modules.
+
+The V compiler modules can be used by V programs that want to
+process V source code in different ways, in fact, that is how
+various V tools are implemented: `v fmt`, `v doc`, `v ast`, `vls`,
+as well as the V compiler itself.
+
 # Compiler pipeline
 A simple high level explanation
 how the compiler pipeline (`parser` -> `checker` -> `generator`) works.

vlib/x/README.md

@@ -0,0 +1,8 @@
+## Description:
+
+`x` is not a module by itself, but a namespace for other modules.
+The modules here are considered experimental/subject to change. 
+
+In time, `x` modules will either become ordinary vlib modules,
+or they will be split to their own repositories, and distributed
+apart from V.