doc: update trim_doc_node_description, make module readmes more uniform (#20792)

cmd/tools/vdoc/tests/testdata/comments/main.comments.out

@@ -2,4 +2,4 @@ module rec
     v doc -f html -o doc rec.v (doc should be an empty folder) I would like to see these 2 lines in HTML-generated header documentation
 
 fn fib(n int) int
-    fib Calculates the recursive fibonacci series `n` is the rank to pass to function I See these 3 lines only
+    fib Calculates the recursive fibonacci series `n` is the rank to pass to function I See these 3 lines only

cmd/tools/vdoc/tests/testdata/comments/main.out

@@ -1,3 +1,3 @@
 module rec
 
-fn fib(n int) int
+fn fib(n int) int

cmd/tools/vdoc/tests/testdata/output_formats/README.md

@@ -1,4 +1,4 @@
-## Description:
+## Description
 
 This is an example of a an .md file, used for adding more rich text
 documentation in a project or module.
@@ -9,9 +9,10 @@ This is a <b>bold text</b>.
 
 This is a script <script>console.log('hi from README.md');</script> .
 
-## Examples:
+## Examples
+
+### Processing command line args
 
-### Processing command line args:
 ```v
 import os
 
@@ -22,7 +23,8 @@ fn main() {
 }
 ```
 
-### A JWT example (test syntax highlighting):
+### A JWT example (test syntax highlighting)
+
 ```v
 import crypto.hmac
 import crypto.sha256

cmd/tools/vdoc/tests/testdata/output_formats/main.ansi

@@ -1,11 +1,11 @@
-Description:
+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:
+Examples
+Processing command line args
 import os
 
 fn main() {
@@ -14,7 +14,7 @@ fn main() {
     assert os.args.len > 0
 }
 
-A JWT example (test syntax highlighting):
+A JWT example (test syntax highlighting)
 import crypto.hmac
 import crypto.sha256
 import encoding.base64
@@ -60,8 +60,7 @@ fn auth_verify(secret string, token string) bool {
     return hmac.equal(signature_from_token, signature_mirror)
 }
 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.
     
@@ -71,9 +70,10 @@ fn auth_verify(secret string, token string) bool {
     
     This is a script <script>console.log('hi from README.md');</script> .
     
-    ## Examples:
+    ## Examples
+    
+    ### Processing command line args
     
-    ### Processing command line args:
     
     ```v
     import os
@@ -85,7 +85,8 @@ fn auth_verify(secret string, token string) bool {
     }
     ```
     
-    ### A JWT example (test syntax highlighting):
+    ### A JWT example (test syntax highlighting)
+    
     ```v
     import crypto.hmac
     import crypto.sha256
@@ -133,6 +134,7 @@ fn auth_verify(secret string, token string) bool {
     }
     ```
     
+
 const omega = 3 // should be first
 const alpha = 5 // should be in the middle
 const beta = 2 // should be at the end

cmd/tools/vdoc/tests/testdata/output_formats/main.html

@@ -1,12 +1,12 @@
 <section id="readme_main" class="doc-node">
 			<div class="title"><h1> main <a href="#readme_main">#</a></h1></div>
-<h2>Description:</h2><p>This is an example of a an .md file, used for adding more rich text documentation in a project or module.</p><p>This is a <a href="https://vlang.io/">link</a> to the main V site.</p><p>This is a <b>bold text</b>.</p><p>This is a script <code>console.log('hi from README.md');</code> .</p><h2>Examples:</h2><h3>Processing command line args:</h3><pre><code class="language-v"><span class="token keyword">import</span> os
+<h2>Description</h2><p>This is an example of a an .md file, used for adding more rich text documentation in a project or module.</p><p>This is a <a href="https://vlang.io/">link</a> to the main V site.</p><p>This is a <b>bold text</b>.</p><p>This is a script <code>console.log('hi from README.md');</code> .</p><h2>Examples</h2><h3>Processing command line args</h3><pre><code class="language-v"><span class="token keyword">import</span> os
 
 <span class="token keyword">fn</span> <span class="token function">main</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
 <span class="token keyword">dump</span><span class="token punctuation">(</span>os<span class="token punctuation">.</span>args<span class="token punctuation">)</span>
 <span class="token keyword">dump</span><span class="token punctuation">(</span>os<span class="token punctuation">.</span>args<span class="token punctuation">.</span>len<span class="token punctuation">)</span>
 <span class="token keyword">assert</span> os<span class="token punctuation">.</span>args<span class="token punctuation">.</span>len <span class="token operator">&</span>gt<span class="token punctuation">;</span> <span class="token number">0</span>
-<span class="token punctuation">}</span></code></pre><h3>A JWT example (test syntax highlighting):</h3><pre><code class="language-v"><span class="token keyword">import</span> crypto<span class="token punctuation">.</span>hmac
+<span class="token punctuation">}</span></code></pre><h3>A JWT example (test syntax highlighting)</h3><pre><code class="language-v"><span class="token keyword">import</span> crypto<span class="token punctuation">.</span>hmac
 <span class="token keyword">import</span> crypto<span class="token punctuation">.</span>sha256
 <span class="token keyword">import</span> encoding<span class="token punctuation">.</span>base64
 <span class="token keyword">import</span> json

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 <script>console.log('hi from README.md');</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

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 {

examples/2048/README.md

@@ -6,12 +6,14 @@ WebAssembly demo: https://v2048.vercel.app
 
 ![screenshot](demo.png)
 
-## 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.

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

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

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

vlib/builtin/README.md

@@ -1,4 +1,4 @@
-## Description:
+## Description
 
 `builtin` is a module that is implicitly imported by every V program.
 

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

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

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`

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

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

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')
 }

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,

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

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.

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('```')
 }

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

vlib/crypto/ed25519/README.md

@@ -1,6 +1,6 @@
-README
------
+## Description
 
-This module implements `ed25519` public key digital signature algorithm for V Language ported </br>
-from `Go` version of `crypto.ed25519`. 
-See [Ed25519](http://ed25519.cr.yp.to/) for more detail about `ed25519`.
+`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`.

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.
+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.

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.
 ```
 

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.

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

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.

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

vlib/fontstash/README.md

@@ -1,4 +1,4 @@
-## Description:
+## 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.

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

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.

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

vlib/io/README.md

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

vlib/js/README.md

@@ -1,4 +1,4 @@
-## Description:
+## Description
 
 `js`  is frontend/browser specific module, that provides access to global JS functions.
 

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
 }
-```
+```

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
 

vlib/maps/README.md

@@ -1,3 +1,3 @@
-## Description:
+## Description
 
 `maps` is a module that provides utility functions to make working with maps easier.

vlib/math/README.md

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

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

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).

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,

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".

vlib/picohttpparser/README.md

@@ -1,4 +1,4 @@
-## Description:
+## Description
 
 `picohttpparser` is V implementation of 
 [picohttpparser](https://github.com/h2o/picohttpparser),

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

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

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()
 }
-```
+```

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.

vlib/strconv/README.md

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

vlib/strings/README.md

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

vlib/sync/README.md

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

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,

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
 

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).
 

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.

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.
 

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

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.