This is an example of a an .md file, used for adding more rich text documentation in a project or module.
This is a link to the main V site.
This is a bold text.
This is a script console.log('hi from README.md'); .
import os
+Description
This is an example of a an .md file, used for adding more rich text documentation in a project or module.
This is a link to the main V site.
This is a bold text.
This is a script console.log('hi from README.md'); .
Examples
Processing command line args
import os
fn main() {
dump(os.args)
dump(os.args.len)
assert os.args.len > 0
-}
A JWT example (test syntax highlighting):
import crypto.hmac
+}
A JWT example (test syntax highlighting)
import crypto.hmac
import crypto.sha256
import encoding.base64
import json
diff --git a/cmd/tools/vdoc/tests/testdata/output_formats/main.text b/cmd/tools/vdoc/tests/testdata/output_formats/main.text
index b837d2c339..d0da79c1f0 100644
--- a/cmd/tools/vdoc/tests/testdata/output_formats/main.text
+++ b/cmd/tools/vdoc/tests/testdata/output_formats/main.text
@@ -1,6 +1,5 @@
module main
-
- ## Description:
+ ## Description
This is an example of a an .md file, used for adding more rich text documentation in a project or module.
@@ -10,9 +9,10 @@ module main
This is a script .
- ## Examples:
+ ## Examples
+
+ ### Processing command line args
- ### Processing command line args:
```v
import os
@@ -24,7 +24,8 @@ module main
}
```
- ### A JWT example (test syntax highlighting):
+ ### A JWT example (test syntax highlighting)
+
```v
import crypto.hmac
import crypto.sha256
@@ -72,6 +73,7 @@ module main
}
```
+
const omega = 3 // should be first
const alpha = 5 // should be in the middle
const beta = 2 // should be at the end
diff --git a/cmd/tools/vdoc/utils.v b/cmd/tools/vdoc/utils.v
index e6538de3c1..00bbb55105 100644
--- a/cmd/tools/vdoc/utils.v
+++ b/cmd/tools/vdoc/utils.v
@@ -33,20 +33,23 @@ fn is_module_readme(dn doc.DocNode) bool {
return dn.comments.len > 0 && dn.content == 'module ${dn.name}'
}
-fn trim_doc_node_description(description string) string {
- mut dn_description := description.replace_each(['\r\n', '\n', '"', '\\"'])
- // 80 is enough to fill one line
- if dn_description.len > 80 {
- dn_description = dn_description[..80]
+fn trim_doc_node_description(desc string) string {
+ mut dn_desc := desc.replace_each(['\r\n', '\n', '"', '\\"'])
+ // Handle module READMEs.
+ if dn_desc.starts_with('## Description\n\n') {
+ dn_desc = dn_desc['## Description\n\n'.len..].all_before('\n')
+ if dn_desc.starts_with('`') && dn_desc.count('`') > 1 {
+ dn_desc = dn_desc.all_after('`').all_after('`').trim_left(' ')
+ }
+ } else {
+ dn_desc = dn_desc.all_before('\n')
}
- if dn_description.contains('\n') {
- dn_description = dn_description.split('\n')[0]
+ // 80 is enough to fill one line.
+ if dn_desc.len > 80 {
+ dn_desc = dn_desc[..80]
}
- // if \ is last character, it ends with \" which leads to a JS error
- if dn_description.ends_with('\\') {
- dn_description = dn_description.trim_right('\\')
- }
- return dn_description
+ // If `\` is last character, it ends with `\"` which leads to a JS error.
+ return dn_desc.trim_string_right('\\')
}
fn set_output_type_from_str(format string) OutputType {
diff --git a/examples/2048/README.md b/examples/2048/README.md
index e166bfa887..ae9ce7fb1c 100644
--- a/examples/2048/README.md
+++ b/examples/2048/README.md
@@ -6,12 +6,14 @@ WebAssembly demo: https://v2048.vercel.app
-## Description:
+## Description
+
Merge tiles by moving them.
-After each move, a new random tile is added (2 or 4).
+After each move, a new random tile is added (2 or 4).
The goal of the game is to create a tile with a value of 2048.
-## Keys:
+## Keys
+
Escape - exit the game
Backspace - undo last move
n - restart the game
@@ -20,34 +22,39 @@ Enter - toggle the tile text format
UP,LEFT,DOWN,RIGHT / W,A,S,D / touchscreen swipes - move the tiles
-## Running instructions:
+## Running instructions
+
Compile & run the game with `./v run examples/2048`
-## Compiling to WASM:
+## Compiling to WASM
1. Install Emscripten from https://emscripten.org/docs/getting_started/downloads.html
2. Make sure that the environment in your shell is setup correctly,
-i.e. that `emcc --version` works.
-```sh
-. /opt/emsdk/emsdk_env.sh
-emcc --version
-```
+ i.e. that `emcc --version` works.
+
+ ```sh
+ . /opt/emsdk/emsdk_env.sh
+ emcc --version
+ ```
3. Compile the game to WASM:
-```sh
-v -skip-unused -prod -os wasm32_emscripten examples/2048/`
-```
+
+ ```sh
+ v -skip-unused -prod -os wasm32_emscripten examples/2048/`
+ ```
4. Copy the 2048 file to `index.js` (can be done once; this step will be removed soon):
-```sh
-cp examples/2048/2048 examples/2048/index.js
-```
+
+ ```sh
+ cp examples/2048/2048 examples/2048/index.js
+ ```
5. Run/test the game:
-```sh
-emrun examples/2048/index.html
-```
+
+ ```sh
+ emrun examples/2048/index.html
+ ```
Once you have run the game, you can make changes,
then just recompile (step 3), and refresh the game in your browser.
diff --git a/vlib/arrays/README.md b/vlib/arrays/README.md
index 99e1ef8c94..c5994be010 100644
--- a/vlib/arrays/README.md
+++ b/vlib/arrays/README.md
@@ -1,8 +1,8 @@
-## Description:
+## Description
`arrays` is a module that provides utility functions to make working with arrays easier.
-## Examples:
+## Examples
```v
import arrays
diff --git a/vlib/benchmark/README.md b/vlib/benchmark/README.md
index d876cb93d0..3c8a48b097 100644
--- a/vlib/benchmark/README.md
+++ b/vlib/benchmark/README.md
@@ -1,8 +1,8 @@
-## Description:
+## Description
`benchmark` provides tools for measuring and reporting on the performance of code.
-## Example 1:
+## Example 1
```v
import benchmark
@@ -29,7 +29,7 @@ intended to be used in combination. Their goal is to make
benchmarking of small snippets of code as _short_, easy to
write, and easy to read and analyze as possible.
-## Example 2:
+## Example 2
```v
import time
diff --git a/vlib/bitfield/README.md b/vlib/bitfield/README.md
index 15c8b93d7a..47ddffc1a9 100644
--- a/vlib/bitfield/README.md
+++ b/vlib/bitfield/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`bitfield` is a module for manipulating arrays of bits,
i.e. series of zeroes and ones spread across an
diff --git a/vlib/builtin/README.md b/vlib/builtin/README.md
index f64a3c49ab..52ddbddca1 100644
--- a/vlib/builtin/README.md
+++ b/vlib/builtin/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`builtin` is a module that is implicitly imported by every V program.
diff --git a/vlib/cli/README.md b/vlib/cli/README.md
index 74fc60dea9..de82900459 100644
--- a/vlib/cli/README.md
+++ b/vlib/cli/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`cli` is a command line option parser, that supports
declarative subcommands, each having separate set of options.
@@ -6,7 +6,7 @@ declarative subcommands, each having separate set of options.
See also the `flag` module, for a simpler command line option parser,
that supports only options.
-## Example:
+## Example
```v
module main
diff --git a/vlib/clipboard/README.md b/vlib/clipboard/README.md
index 86e6c41d13..40d4caa3f4 100644
--- a/vlib/clipboard/README.md
+++ b/vlib/clipboard/README.md
@@ -1,10 +1,10 @@
-## Description:
+## 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.
-## Examples:
+## Examples
```v
import clipboard
diff --git a/vlib/compress/README.md b/vlib/compress/README.md
index 30ebdb169e..ad0082eb82 100644
--- a/vlib/compress/README.md
+++ b/vlib/compress/README.md
@@ -1,8 +1,9 @@
-## Description:
+## Description
`compress` is a namespace for (multiple) compression algorithms supported by V.
At the moment, the following compression algorithms are implemented:
+
- `compress.deflate`
- `compress.gzip`
- `compress.zlib`
diff --git a/vlib/compress/deflate/README.md b/vlib/compress/deflate/README.md
index 23ef657ff1..9aa198d3ab 100644
--- a/vlib/compress/deflate/README.md
+++ b/vlib/compress/deflate/README.md
@@ -1,10 +1,9 @@
-## Description:
+## Description
`compress.deflate` is a module that assists in the compression and
decompression of binary data using `deflate` compression
-
-## Examples:
+## Example
```v
import compress.deflate
diff --git a/vlib/compress/gzip/README.md b/vlib/compress/gzip/README.md
index 76edf2daa3..d219b0f68b 100644
--- a/vlib/compress/gzip/README.md
+++ b/vlib/compress/gzip/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`compress.gzip` is a module that assists in the compression and
decompression of binary data using `gzip` compression
diff --git a/vlib/compress/gzip/read_gz_files_test.v b/vlib/compress/gzip/read_gz_files_test.v
index c2c9e5543c..ef1436f53d 100644
--- a/vlib/compress/gzip/read_gz_files_test.v
+++ b/vlib/compress/gzip/read_gz_files_test.v
@@ -18,7 +18,7 @@ fn test_reading_and_decoding_a_known_gziped_file() {
compressed, content := read_and_decode_file(s('known.gz'))!
assert compressed#[0..3] == [u8(31), 139, 8]
assert compressed#[-5..] == [u8(127), 115, 1, 0, 0]
- assert content.contains('## Description:')
+ assert content.contains('## Description')
assert content.contains('## Examples:')
assert content.ends_with('```\n')
}
diff --git a/vlib/compress/szip/README.md b/vlib/compress/szip/README.md
index 93b6a53edc..48f19307a3 100644
--- a/vlib/compress/szip/README.md
+++ b/vlib/compress/szip/README.md
@@ -1,4 +1,4 @@
-## Description:
+## 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,
diff --git a/vlib/compress/zlib/README.md b/vlib/compress/zlib/README.md
index d83a22594e..9436ae3f4a 100644
--- a/vlib/compress/zlib/README.md
+++ b/vlib/compress/zlib/README.md
@@ -1,9 +1,9 @@
-## Description:
+## Description
`compress.zlib` is a module that assists in the compression and
decompression of binary data using `zlib` compression
-## Examples:
+## Examples
```v
import compress.zlib
diff --git a/vlib/compress/zstd/README.md b/vlib/compress/zstd/README.md
index 7e11fe7ac0..cc61c5c745 100644
--- a/vlib/compress/zstd/README.md
+++ b/vlib/compress/zstd/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`compress.zstd` is a module that assists in the compression and
decompression of binary data using `zstd` compression.
diff --git a/vlib/compress/zstd/read_zstd_files_test.v b/vlib/compress/zstd/read_zstd_files_test.v
index 5d0bb99395..d7c1071df8 100644
--- a/vlib/compress/zstd/read_zstd_files_test.v
+++ b/vlib/compress/zstd/read_zstd_files_test.v
@@ -18,7 +18,7 @@ fn test_reading_and_decoding_a_known_zstded_file() {
compressed, content := read_and_decode_file(s('known.zst'))!
assert compressed#[0..3] == [u8(40), 181, 47]
assert compressed#[-5..] == [u8(10), 78, 32, 170, 44]
- assert content.contains('## Description:')
+ assert content.contains('## Description')
assert content.contains('## Examples:')
assert content.ends_with('```')
}
diff --git a/vlib/crypto/README.md b/vlib/crypto/README.md
index 32e8894352..4f3878439b 100644
--- a/vlib/crypto/README.md
+++ b/vlib/crypto/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`crypto` is a module that exposes cryptographic algorithms to V programs.
@@ -13,9 +13,10 @@ to create a destination buffer of the correct size to receive the decrypted data
The implementations here are loosely based on [Go's crypto package](https://pkg.go.dev/crypto).
-## Examples:
+## Examples
+
+### AES
-### AES:
```v
import crypto.aes
import crypto.rand
@@ -45,7 +46,8 @@ fn main() {
}
```
-### JWT:
+### JWT
+
```v
import crypto.hmac
import crypto.sha256
diff --git a/vlib/crypto/ed25519/README.md b/vlib/crypto/ed25519/README.md
index 01b04de434..ab786c42c2 100644
--- a/vlib/crypto/ed25519/README.md
+++ b/vlib/crypto/ed25519/README.md
@@ -1,6 +1,6 @@
-README
------
+## Description
-This module implements `ed25519` public key digital signature algorithm for V Language ported
-from `Go` version of `crypto.ed25519`.
-See [Ed25519](http://ed25519.cr.yp.to/) for more detail about `ed25519`.
\ No newline at end of file
+`crypto.ed25519` implements the `ed25519` public key digital signature algorithm for the V Language.
+The module is proted from the `Go` version of `crypto.ed25519`.
+
+See [Ed25519](http://ed25519.cr.yp.to/) for more detail about `ed25519`.
diff --git a/vlib/crypto/ed25519/internal/edwards25519/README.md b/vlib/crypto/ed25519/internal/edwards25519/README.md
index be0eb47fdb..297b15fee4 100644
--- a/vlib/crypto/ed25519/internal/edwards25519/README.md
+++ b/vlib/crypto/ed25519/internal/edwards25519/README.md
@@ -1,19 +1,17 @@
-README
--------
+## Description
+
+`crypto.ed25519.internal.edwards25519` provides arithmetic primitives operations that are useful to
+implement cryptographic schemes over the edwards25519 elliptic curve, including:
-This module provides arithmetic primitives operations that are useful to implement
-cryptographic schemes over curve edwards25519, includes:
1. Arithmetic functions for point addition, doubling, negation, scalar multiplication
with an arbitrary point, with the base point, etc.
2. Arithmetic functions dealing with scalars modulo the prime order L of the base point.
This modules was port of Golang `edwards25519` library from [edwards25519](https://github.com/FiloSottile/edwards25519) to the V language.
+## About Edwards25519
-About Edwards25519
-------------------
-
-Twisted Edwards curves are a family of elliptic curves allowing complete addition
-formulas without any special case and no point at infinity.
-Curve edwards25519 is based on prime 2^255 - 19 for efficient implementation.
-Equation and parameters are given in RFC 7748.
\ No newline at end of file
+Twisted Edwards curves are a family of elliptic curves allowing complete addition
+formulas without any special case and no point at infinity.
+Curve edwards25519 is based on prime 2^255 - 19 for efficient implementation.
+Equation and parameters are given in RFC 7748.
diff --git a/vlib/db/pg/README.md b/vlib/db/pg/README.md
index d9349d94e3..a201b413c5 100644
--- a/vlib/db/pg/README.md
+++ b/vlib/db/pg/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`pg` is a wrapper for the PostgreSQL client library. It provides access to a PostgreSQL
database server.
@@ -11,6 +11,7 @@ To do this, find your OS and perform the actions listed.
> or you need extra help, [go here](https://www.postgresql.org/download/).
### Fedora 31
+
```
sudo dnf install postgresql-server postgresql-contrib
sudo systemctl enable postgresql # to autostart on startup
@@ -18,6 +19,7 @@ sudo systemctl start postgresql
```
### Ubuntu/Debian
+
```
sudo apt-get install postgresql postgresql-client
sudo systemctl enable postgresql # to autostart on startup
@@ -25,17 +27,19 @@ sudo systemctl start postgresql
```
### MacOSX (Homebrew)
+
```
brew install postgresql
brew services start postgresql
```
### MacOSX (MacPorts)
+
```
gem install pg -- --with-pg-config=/opt/local/lib/postgresql[version number]/bin/pg_config
```
-## Installing libpq-dev or its equivalent for your OS: ##
+## Installing libpq-dev or its equivalent for your OS:
**Ubuntu/Debian**: `sudo apt-get install libpq-dev`
@@ -46,6 +50,7 @@ gem install pg -- --with-pg-config=/opt/local/lib/postgresql[version number]/bin
**ArchLinux**: `pacman -S postgresql-libs`
**Windows**:
+
```
1. Download PostgreSQL SDK from official site
2. Extract archive to postgres-master folder
@@ -74,7 +79,7 @@ If you are going to use the msvc compiler:
8. Add libpq.dll, libcrypto-3-x64.dll, libssl-3-x64.dll to where your executable is.
-To get the libpq.dll file, you can install the PostgreSQL database,
+To get the libpq.dll file, you can install the PostgreSQL database,
and get this dll from its bin/ folder, or compile DB from source code.
```
diff --git a/vlib/dl/README.md b/vlib/dl/README.md
index 060cbfeee0..2abc4c19cc 100644
--- a/vlib/dl/README.md
+++ b/vlib/dl/README.md
@@ -1,4 +1,4 @@
-## Description:
+## 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.
diff --git a/vlib/dl/loader/README.md b/vlib/dl/loader/README.md
index 5a9580ba82..0a73821933 100644
--- a/vlib/dl/loader/README.md
+++ b/vlib/dl/loader/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`dl.loader` is an abstraction layer over `dl` that provides a more user-friendly API in the V way.
It can be used to Dynamically Load a library during runtime in scenarios where the library to load
@@ -7,7 +7,7 @@ does not have a determined path an can be located in different places.
It also provides a way to load a library from a specific path, or from a list of paths, or from
a custom environment variable that contains a list of paths.
-## Usage:
+## Usage
```v
import dl.loader
diff --git a/vlib/encoding/README.md b/vlib/encoding/README.md
index 7a711f5835..16252a1db9 100644
--- a/vlib/encoding/README.md
+++ b/vlib/encoding/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`encoding` is a namespace for different formats/protocols encoding/decoding,
like `csv`, `utf8`, `base64` etc.
diff --git a/vlib/flag/README.md b/vlib/flag/README.md
index da1b8a4cd0..965cd44167 100644
--- a/vlib/flag/README.md
+++ b/vlib/flag/README.md
@@ -1,7 +1,8 @@
-## Description:
+## 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.
@@ -12,7 +13,7 @@ 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:
+## Examples
```v
module main
diff --git a/vlib/fontstash/README.md b/vlib/fontstash/README.md
index 099f4dd0c1..dec615e2b3 100644
--- a/vlib/fontstash/README.md
+++ b/vlib/fontstash/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`fontstash` is a thin wrapper over ,
which in turn is a light-weight online font texture atlas builder written in C.
diff --git a/vlib/gg/README.md b/vlib/gg/README.md
index 63be986c22..6cf111abdf 100644
--- a/vlib/gg/README.md
+++ b/vlib/gg/README.md
@@ -1,11 +1,11 @@
-## Description:
+## 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:
+## Example
```v cgen
module main
diff --git a/vlib/gx/README.md b/vlib/gx/README.md
index 91a0579f11..21b9b5ec48 100644
--- a/vlib/gx/README.md
+++ b/vlib/gx/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`gx` is a complementary module to `gg`, that just provides
some predefined graphical color names/operations.
diff --git a/vlib/hash/README.md b/vlib/hash/README.md
index 075bd85f67..0c779121a4 100644
--- a/vlib/hash/README.md
+++ b/vlib/hash/README.md
@@ -1,4 +1,4 @@
-## Description:
+## 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
diff --git a/vlib/io/README.md b/vlib/io/README.md
index 5ff1887f8f..6133a77ae1 100644
--- a/vlib/io/README.md
+++ b/vlib/io/README.md
@@ -1,3 +1,3 @@
-## Description:
+## Description
`io` provides common interfaces for buffered reading/writing of data.
diff --git a/vlib/js/README.md b/vlib/js/README.md
index 452fcdcc18..586e0e98f1 100644
--- a/vlib/js/README.md
+++ b/vlib/js/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`js` is frontend/browser specific module, that provides access to global JS functions.
diff --git a/vlib/json/README.md b/vlib/json/README.md
index a21a3a6038..269c6e2a95 100644
--- a/vlib/json/README.md
+++ b/vlib/json/README.md
@@ -1,9 +1,10 @@
-## Description:
+## Description
The `json` module provides encoding/decoding of V data structures to/from JSON.
-For more details, see also the
+For more details, see also the
[JSON section of the V documentation](https://github.com/vlang/v/blob/master/doc/docs.md#json)
-## Examples:
+
+## Examples
Here is an example of encoding and decoding a V struct with several fields.
Note that you can specify different names in the json encoding for the fields,
@@ -45,4 +46,4 @@ fn main() {
println('JSON encoding of employee y: ${ss}')
assert ss == s
}
-```
\ No newline at end of file
+```
diff --git a/vlib/log/README.md b/vlib/log/README.md
index fdb643c47f..7101f016cb 100644
--- a/vlib/log/README.md
+++ b/vlib/log/README.md
@@ -1,16 +1,18 @@
-## Description:
+## 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.
-## Basic usage:
+## Basic usage
+
The log module creates a default Log instance by default, and
provides utility functions, that you can use to access it.
Note: the default Log instance is thread safe.
That makes it very convenient to use in subsystems, without having
to thread a log instance everywhere:
+
```v
import log
@@ -30,9 +32,11 @@ log.debug('a debug message')
abc()
```
-## Advanced usage:
+## Advanced usage
+
You can also create your own log instances, with different options
applied to them:
+
```v
import log
diff --git a/vlib/maps/README.md b/vlib/maps/README.md
index a6eb9a91c4..42d7c26395 100644
--- a/vlib/maps/README.md
+++ b/vlib/maps/README.md
@@ -1,3 +1,3 @@
-## Description:
+## Description
`maps` is a module that provides utility functions to make working with maps easier.
diff --git a/vlib/math/README.md b/vlib/math/README.md
index 2b78b3bb94..940ca91851 100644
--- a/vlib/math/README.md
+++ b/vlib/math/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`math` provides commonly used mathematical functions for
trigonometry, logarithms, etc.
diff --git a/vlib/net/README.md b/vlib/net/README.md
index 3ee7b6e3c3..1ac0eb9e0a 100644
--- a/vlib/net/README.md
+++ b/vlib/net/README.md
@@ -1,4 +1,4 @@
-## Description:
+## 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
diff --git a/vlib/net/conv/README.md b/vlib/net/conv/README.md
index 6d31db85da..a78c03c439 100644
--- a/vlib/net/conv/README.md
+++ b/vlib/net/conv/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`net.conv` provides a convenient way to convert number values *to*,
and *from* the network byte order format (which is always big endian).
diff --git a/vlib/os/README.md b/vlib/os/README.md
index c4537eca79..bbfa0d3bdf 100644
--- a/vlib/os/README.md
+++ b/vlib/os/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`os` provides common OS/platform independent functions for accessing
command line arguments, reading/writing files, listing folders,
diff --git a/vlib/picoev/README.md b/vlib/picoev/README.md
index f4419cfa98..91d83ce7a1 100644
--- a/vlib/picoev/README.md
+++ b/vlib/picoev/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`picoev` is a V implementation of [picoev](https://github.com/kazuho/picoev),
which in turn is "A tiny, lightning fast event loop for network applications".
diff --git a/vlib/picohttpparser/README.md b/vlib/picohttpparser/README.md
index 79c116d151..f557f1dfbe 100644
--- a/vlib/picohttpparser/README.md
+++ b/vlib/picohttpparser/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`picohttpparser` is V implementation of
[picohttpparser](https://github.com/h2o/picohttpparser),
diff --git a/vlib/runtime/README.md b/vlib/runtime/README.md
index ca2a982795..669c0129d2 100644
--- a/vlib/runtime/README.md
+++ b/vlib/runtime/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`runtime` provides access to functions describing the current platform:
- whether it is 32bit or 64bit
diff --git a/vlib/semver/README.md b/vlib/semver/README.md
index e5a7a2beb2..ef21341048 100644
--- a/vlib/semver/README.md
+++ b/vlib/semver/README.md
@@ -1,8 +1,8 @@
-## Description:
+## Description
`semver` is a library for processing versions, that use the [semver][semver] format.
-## Examples:
+## Examples
```v
import semver
diff --git a/vlib/sokol/README.md b/vlib/sokol/README.md
index db764ef19d..29abcff3ac 100644
--- a/vlib/sokol/README.md
+++ b/vlib/sokol/README.md
@@ -1,4 +1,4 @@
-## Description:
+## 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
@@ -9,7 +9,7 @@ Each `.h` file in the sokol source code is well-documented as can be seen here:
[sokol_audio.h](https://github.com/floooh/sokol/blob/master/sokol_audio.h)
-## Example from `@VROOTDIR/examples/sokol/sounds/simple_sin_tones.v`:
+## Example from `@VROOTDIR/examples/sokol/sounds/simple_sin_tones.v`
```v cgen
import time
@@ -52,4 +52,4 @@ fn main() {
time.sleep(2000 * time.millisecond)
audio.shutdown()
}
-```
\ No newline at end of file
+```
diff --git a/vlib/stbi/README.md b/vlib/stbi/README.md
index 50954dde6d..82c5e52baa 100644
--- a/vlib/stbi/README.md
+++ b/vlib/stbi/README.md
@@ -1,4 +1,4 @@
-## Description:
+## 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.
diff --git a/vlib/strconv/README.md b/vlib/strconv/README.md
index 574afc132c..bb8f04e501 100644
--- a/vlib/strconv/README.md
+++ b/vlib/strconv/README.md
@@ -1,3 +1,3 @@
-## Description:
+## Description
`strconv` provides functions for converting strings to numbers and numbers to strings.
diff --git a/vlib/strings/README.md b/vlib/strings/README.md
index 779f891a11..63e2e769b6 100644
--- a/vlib/strings/README.md
+++ b/vlib/strings/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`strings` provides utilities for efficiently processing large strings.
diff --git a/vlib/sync/README.md b/vlib/sync/README.md
index eee85f147b..f7afa4486a 100644
--- a/vlib/sync/README.md
+++ b/vlib/sync/README.md
@@ -1,3 +1,3 @@
-## Description:
+## Description
`sync` provides cross platform handling of concurrency primitives.
diff --git a/vlib/szip/README.md b/vlib/szip/README.md
index 4d4f9528c6..d8899ad52b 100644
--- a/vlib/szip/README.md
+++ b/vlib/szip/README.md
@@ -1,4 +1,4 @@
-## Description:
+## 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,
diff --git a/vlib/time/README.md b/vlib/time/README.md
index b653cd8f62..1cf79f4d34 100644
--- a/vlib/time/README.md
+++ b/vlib/time/README.md
@@ -1,6 +1,7 @@
-## Description:
+## Description
V's `time` module, 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
@@ -8,9 +9,10 @@ V's `time` module, provides utilities for working with time and dates:
- stop watches for accurately measuring time durations
- sleeping for a period of time
-## Examples:
+## Examples
You can see the current time. [See](https://play.vlang.io/?query=c121a6dda7):
+
```v
import time
@@ -18,6 +20,7 @@ println(time.now())
```
`time.Time` values can be compared, [see](https://play.vlang.io/?query=133d1a0ce5):
+
```v
import time
@@ -43,6 +46,7 @@ assert '1980-07-11 21:23:42.123456789' == time_to_test.format_ss_nano()
You can also parse strings to produce time.Time values,
[see](https://play.vlang.io/p/b02ca6027f):
+
```v
import time
@@ -53,6 +57,7 @@ println(t.unix)
```
V's time module also has these parse methods:
+
```v ignore
fn parse(s string) !Time
fn parse_iso8601(s string) !Time
@@ -63,6 +68,7 @@ fn parse_rfc3339(s string) !Time
Another very useful feature of the `time` module is the stop watch,
for when you want to measure short time periods, elapsed while you
executed other tasks. [See](https://play.vlang.io/?query=f6c008bc34):
+
```v
import time
diff --git a/vlib/toml/README.md b/vlib/toml/README.md
index 4ab9aac2d0..1f243b8f77 100644
--- a/vlib/toml/README.md
+++ b/vlib/toml/README.md
@@ -1,4 +1,5 @@
## 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).
diff --git a/vlib/v/token/README.md b/vlib/v/token/README.md
index 4ff52539af..4933bc1d0a 100644
--- a/vlib/v/token/README.md
+++ b/vlib/v/token/README.md
@@ -1,9 +1,10 @@
-## Description:
+## Description
`v.token` is a module providing the basic building blocks of the V
syntax - the tokens, as well as utilities for working with them.
-## KeywordsMatcherTrie
+## KeywordsMatcherTrie
+
KeywordsMatcherTrie provides a faster way of determining whether a given name is a reserved
word (belongs to a given set of previously known words `R`). It works by exploiting the fact,
that the set of reserved words is small, and the words short.
@@ -22,6 +23,7 @@ any given prefix, belonging to `R`.
For example, if we have added the word `asm` to the trie T3, its tree (its nodes) may look
like this (note that the 0 pointers in children, mean that there was no word in `R`, that had
that corresponding letter at that specific index):
+
```
TrieNode 0: a b c d e f g h i j k l m n o p q r s t u v w x y z ... |
| children: 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ... | children[`a`] = 1 -> TrieNode 1
@@ -45,13 +47,13 @@ Matching any given `word` in the trie, after you have prepared it, is then simpl
just read each character of the `word`, and follow the corresponding pointer from
the `children` array (indexed by character). When the pointer is nil, there was NO
match, and the word is rejected, which happens very often, and early for most words
-that are not in the set of the previously added reserved words. One significant
+that are not in the set of the previously added reserved words. One significant
benefit compared to just comparing the checked `word` against a linear list of all
known words, is that once you have found that a word is not a match at any given
level/trie node, then you know that it is not a match to *any* of them.
-Note: benchmarking shows that it is ~300% to 400% faster, compared to just using
+Note: benchmarking shows that it is ~300% to 400% faster, compared to just using
`token.keywords[name]` on average, when there is a match, but it can be 17x faster
in the case, where there is a length mismatch. After changes to KeywordsMatcherTrie,
-please do `v -prod run vlib/v/tests/bench/bench_compare_tokens.v` to verify,
+please do `v -prod run vlib/v/tests/bench/bench_compare_tokens.v` to verify,
that there is no performance regression.
diff --git a/vlib/wasm/README.md b/vlib/wasm/README.md
index c028968743..66e9af42a4 100644
--- a/vlib/wasm/README.md
+++ b/vlib/wasm/README.md
@@ -1,12 +1,12 @@
-## Description:
+## Description
-The `wasm` module is a pure V implementation of the WebAssembly bytecode module format,
+The `wasm` module is a pure V implementation of the WebAssembly bytecode module format,
available in the form of a builder.
-It allows users to generate WebAssembly modules in memory.
+It allows users to generate WebAssembly modules in memory.
With the V wasm module, users can create functions, opcodes, and utilize the entire wasm
-specification without the need for a large dependency like binaryen. All of this
+specification without the need for a large dependency like binaryen. All of this
functionality is available within V itself, making the module a valuable resource for
V developers seeking to build high-performance web applications.
diff --git a/vlib/x/README.md b/vlib/x/README.md
index 8392a17ff3..4915ae3b30 100644
--- a/vlib/x/README.md
+++ b/vlib/x/README.md
@@ -1,7 +1,7 @@
-## Description:
+## Description
`x` is not a module by itself, but a namespace for other modules.
-The modules here are considered experimental/subject to change.
+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
diff --git a/vlib/x/crypto/sm4/README.md b/vlib/x/crypto/sm4/README.md
index 4e52d46a7b..3627c708c3 100644
--- a/vlib/x/crypto/sm4/README.md
+++ b/vlib/x/crypto/sm4/README.md
@@ -1,4 +1,4 @@
-## Description:
+## Description
`crypto.sm4` is a module that assists in the encryption and
decryption of binary data using the `SM4` block cipher.