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
+`bitfield` is a module for manipulating arrays of bits, i.e. series of zeroes
-manipulating arrays of bits, i.e. series of zeroes and ones spread across an
+and ones spread across an array of storage units (unsigned 32-bit integers).
-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 (
+pub const version = 1
-	version = 1
+
-	dl_ext  = get_shared_library_extension()
+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 (
+pub const rtld_now = C.RTLD_NOW
-	rtld_now  = C.RTLD_NOW
+
-	rtld_lazy = C.RTLD_LAZY
+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 (
+pub const rtld_now = 0
-	rtld_now  = 0
+
-	rtld_lazy = 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.
+## Description:
-Main features are:
+
+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,3 +1,8 @@
+## 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.
 

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:
 

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]
 

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,8 +1,8 @@
-# semver
+## Description:
 
-A library for working with versions in [semver][semver] format.
+`semver` is a library for processing versions, that use the [semver][semver] format.
 
-## Usage
+## Examples:
 
 ```v
 import semver

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
+The `term` module is designed to provide the building blocks for building
-for building very simple TUI apps.
+very simple TUI apps. For more complex apps, you should really look at the
-For more complex apps, you should really look at the `term.input` module,
+`term.input` module, as it includes terminal events, is easier to use and
-as it includes terminal events, is easier to use and is much more performant for large draws.
+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.