Merge pull request #3428 from mgavioli/fix_core_docs

Fix the format of some `doc.odin` files of the `core` library…

core/c/frontend/tokenizer/doc.odin

@@ -1,4 +1,5 @@
 /*
+Example:
 	package demo
 
 	import tokenizer "core:c/frontend/tokenizer"
@@ -27,8 +28,4 @@ main :: proc() {
 		fmt.println("[Done]");
 	}
 */
-
-
 package c_frontend_tokenizer
-
-

core/container/bit_array/doc.odin

@@ -1,9 +1,7 @@
-package dynamic_bit_array
-
 /*
 The Bit Array can be used in several ways:
 
-	-- By default you don't need to instantiate a Bit Array:
+- By default you don't need to instantiate a Bit Array:
 
 	package test
 
@@ -24,7 +22,7 @@ package dynamic_bit_array
 		destroy(&bits)
 	}
 
-	-- A Bit Array can optionally allow for negative indices, if the mininum value was given during creation:
+- A Bit Array can optionally allow for negative indices, if the minimum value was given during creation:
 
 	package test
 
@@ -51,3 +49,4 @@ package dynamic_bit_array
 		fmt.printf("Freed.\n")
 	}
 */
+package dynamic_bit_array

core/dynlib/doc.odin

@@ -1,6 +1,5 @@
-//+build ignore
 /*
-Package core:dynlib implements loading of shared libraries/DLLs and their symbols.
+Package `core:dynlib` implements loading of shared libraries/DLLs and their symbols.
 
 The behaviour of dynamically loaded libraries is specific to the target platform of the program.
 For in depth detail on the underlying behaviour please refer to your target platform's documentation.

core/image/netpbm/doc.odin

@@ -1,5 +1,6 @@
 /*
 Formats:
+
 	PBM (P1, P4): Portable Bit Map,       stores black and white images   (1 channel)
 	PGM (P2, P5): Portable Gray Map,      stores greyscale images         (1 channel, 1 or 2 bytes per value)
 	PPM (P3, P6): Portable Pixel Map,     stores colour images            (3 channel, 1 or 2 bytes per value)
@@ -7,27 +8,29 @@ Formats:
 	PFM (Pf, PF): Portable Float Map,     stores floating-point images    (Pf: 1 channel, PF: 3 channel)
 
 Reading:
-	All formats fill out header fields `format`, `width`, `height`, `channels`, `depth`
+
-	Specific formats use more fields
+- All formats fill out header fields `format`, `width`, `height`, `channels`, `depth`.
+- Specific formats use more fields:
 	PGM, PPM, and PAM set `maxval` (maximum of 65535)
 	PAM sets `tupltype` if there is one, and can set `channels` to any value (not just 1 or 3)
 	PFM sets `scale` (float equivalent of `maxval`) and `little_endian` (endianness of stored floats)
-	Currently doesn't support reading multiple images from one binary-format file
+- Currently doesn't support reading multiple images from one binary-format file.
 
 Writing:
-	You can use your own `Netpbm_Info` struct to control how images are written
+
-	All formats require the header field `format` to be specified
+- You can use your own `Netpbm_Info` struct to control how images are written.
-	Additional header fields are required for specific formats
+- All formats require the header field `format` to be specified.
+- Additional header fields are required for specific formats:
 	PGM, PPM, and PAM require `maxval` (maximum of 65535)
 	PAM also uses `tupltype`, though it may be left as default (empty or nil string)
 	PFM requires `scale`, and optionally `little_endian`
 
 Some syntax differences from the specifications:
-	`channels` stores the number of values per pixel, what the PAM specification calls `depth`
-	`depth` instead is the number of bits for a single value (32 for PFM, 16 or 8 otherwise)
-	`scale` and `little_endian` are separated, so the `header` will always store a positive `scale`
-	`little_endian` will only be true for a negative `scale` PFM, every other format will be false
-	`little_endian` only describes the netpbm data being read/written, the image buffer will be native
-*/
 
+- `channels` stores the number of values per pixel, what the PAM specification calls `depth`
+- `depth` instead is the number of bits for a single value (32 for PFM, 16 or 8 otherwise)
+- `scale` and `little_endian` are separated, so the `header` will always store a positive `scale`
+- `little_endian` will only be true for a negative `scale` PFM, every other format will be false
+- `little_endian` only describes the netpbm data being read/written, the image buffer will be native
+*/
 package netpbm

core/sys/info/doc.odin

@@ -12,9 +12,8 @@
 
 CPU feature flags can be tested against `cpu_features`, where applicable, e.g.
 `if .aes in si.aes { ... }`
-*/
+
-//+build ignore
+Example:
-package sysinfo
 
 	import "core:fmt"
 	import si "core:sys/info"
@@ -35,8 +34,8 @@ main :: proc() {
 		}
 	}
 
-/*
+- Example Windows output:
-	Example Windows output:
+
 	Odin:  dev-2022-09
 	OS:    Windows 10 Professional (version: 20H2), build: 19042.1466
 	OS:    OS_Version{
@@ -53,13 +52,13 @@ main :: proc() {
 	}
 	CPU:   AMD Ryzen 7 1800X Eight-Core Processor
 	RAM:   65469 MiB
-
 	GPU #0:
 		Vendor: Advanced Micro Devices, Inc.
 		Model:  Radeon RX Vega
 		VRAM:   8176 MiB
 
-	Example macOS output:
+- Example macOS output:
+
 	ODIN: dev-2022-09
 	OS:   OS_Version{
 			platform = "MacOS",
@@ -76,3 +75,4 @@ main :: proc() {
 	CPU:  Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz
 	RAM:  8192 MiB
 */
+package sysinfo

core/text/i18n/doc.odin

@@ -1,8 +1,6 @@
-//+build ignore
-package i18n
 
 /*
-	The i18n package is flexible and easy to use.
+The `i18n` package is flexible and easy to use.
 
 It has one call to get a translation: `get`, which the user can alias into something like `T`.
 
@@ -21,7 +19,7 @@ package i18n
 - `T(key, n, catalog)`           returns the pluralized version of `key` from explictly supplied catalog.
 - `T(section, key, n, catalog)`  returns the pluralized version of `key` in `section` from explictly supplied catalog.
 
-	If a catalog has translation contexts or sections, then ommitting it in the above calls looks up in section "".
+If a catalog has translation contexts or sections, then omitting it in the above calls looks up in section "".
 
 The default pluralization rule is n != 1, which is to say that passing n == 1 (or not passing n) returns the singular form.
 Passing n != 1 returns plural form 1.
@@ -31,11 +29,8 @@ package i18n
 
 You can also assign it to a loaded catalog after parsing, of course.
 
-	Some code examples follow.
+Example:
-*/
 
-/*
-```cpp
 	import "core:fmt"
 	import "core:text/i18n"
 
@@ -107,5 +102,5 @@ qt :: proc() {
 		println("\t 1  =", T("apple_count", "%d apple(s)", 1))
 		println("\t 42 =", T("apple_count", "%d apple(s)", 42))
 	}
-```
 */
+package i18n

core/text/table/doc.odin

@@ -1,11 +1,8 @@
 /*
-	package table implements ascii/markdown/html/custom rendering of tables.
+The package `table` implements ASCII/markdown/HTML/custom rendering of tables.
 
-	---
+**Custom rendering example:**
 
-	Custom rendering example:
-
-	```odin
 	tbl := init(&Table{})
 	padding(tbl, 0, 1)
 	row(tbl, "A_LONG_ENUM", "= 54,", "// A comment about A_LONG_ENUM")
@@ -17,19 +14,14 @@
 		}
 		io.write_byte(stdio_writer(), '\n')
 	}
-	```
 
 This outputs:
-	```
+
 	A_LONG_ENUM         = 54, // A comment about A_LONG_ENUM
 	AN_EVEN_LONGER_ENUM = 1,  // A comment about AN_EVEN_LONGER_ENUM
-	```
 
-	---
+**ASCII rendering example:**
 
-	ASCII rendering example:
-
-	```odin
 	tbl := init(&Table{})
 	defer destroy(tbl)
 
@@ -69,10 +61,9 @@
 
 	write_ascii_table(stdio_writer(), tbl)
 	write_markdown_table(stdio_writer(), tbl)
-	```
 
 This outputs:
-	```
+
 	+-----------------------------------------------+
 	|  This is a table caption and it is very long  |
 	+------------------+-----------------+----------+
@@ -82,19 +73,15 @@
 	| 000000005        | 6.283185        |          |
 	|        a         | bbb             | c        |
 	+------------------+-----------------+----------+
-	```
 
 and
 
-	```
 	|    AAAAAAAAA     |        B        |    C     |
 	|:-----------------|:---------------:|---------:|
 	| 123              | foo             |          |
 	| 000000005        | 6.283185        |          |
 	| a                | bbb             | c        |
-	```
 
 respectively.
 */
-
 package text_table