Fix the format of some doc.odin files of the core library which did not made into the documentation.

`c/frontend/tokenizer`:
   add proper "Example:" header to demo example code,
   removed empty lines.
`container/bit_array`:
   moved comment before package;
   aligned narrative lines to left margin;
   converted case lines into bulleted lines ("- ");
   converted individual examples to single-tab-indented preformatted text.
`dynlib`:
   removed "//+build ignore" line;
   added newline at EOF.
`image/netpmb`:
   converted indented lines of "Reading", "Wrting" and "Some syntax..." into bulleted lists;
   "Formats" indented lines kept as they are as the preformatted text seems relevant to keep the alignments;
   doubly indented lines kept as single-indented to keep them different (as the format does not allow for two-level bulleted lists);
   removed empy lines.
`os/os2`:	WIP, not modified
`sys/info`:
   removed "//+build ignore" line;
   converted tab-indented initial description into regular left-margin comment;
   moved uncommented sample code within the doc comment as an "Example:";
   moved simple- and double-tabbed separate comments with sample Windows and macOS outputs within the doc comment as bulleted headlines with preformatted output listings;
   removed now empty comments and blank lines after the package line.
`text/i18n`:
   removed "//+build ignore" line;
   moved the pacakge line at the end;
   de-indented the tab-indented introductory narrative;
   moved sample code comments into the doc comment as tab-indented code with a proper "Example:" heading;
   removed "```" MD attempts at code formatting.
`text/table`:
   unindented the comment lines of a descriptive kind;
   headlines of major subdivisions are marked as bold;
   kept code samples as tab-indented preformatted text (as there are several of them, the standard "Example:" and "Output:" headings cannot be used) removing the "```" MD attempts at code formatting;
   removed in-between blank lines.
This commit is contained in:
Maurizio M. Gavioli
2024-04-14 17:18:08 +02:00
parent 21969fec61
commit a0cff82320
7 changed files with 240 additions and 260 deletions
+1 -4
View File
@@ -1,4 +1,5 @@
/* /*
Example:
package demo package demo
import tokenizer "core:c/frontend/tokenizer" import tokenizer "core:c/frontend/tokenizer"
@@ -27,8 +28,4 @@ main :: proc() {
fmt.println("[Done]"); fmt.println("[Done]");
} }
*/ */
package c_frontend_tokenizer package c_frontend_tokenizer
+3 -4
View File
@@ -1,9 +1,7 @@
package dynamic_bit_array
/* /*
The Bit Array can be used in several ways: 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 package test
@@ -24,7 +22,7 @@ package dynamic_bit_array
destroy(&bits) 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 package test
@@ -51,3 +49,4 @@ package dynamic_bit_array
fmt.printf("Freed.\n") fmt.printf("Freed.\n")
} }
*/ */
package dynamic_bit_array
+1 -2
View File
@@ -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. 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. For in depth detail on the underlying behaviour please refer to your target platform's documentation.
+15 -12
View File
@@ -1,5 +1,6 @@
/* /*
Formats: Formats:
PBM (P1, P4): Portable Bit Map, stores black and white images (1 channel) 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) 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) 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) PFM (Pf, PF): Portable Float Map, stores floating-point images (Pf: 1 channel, PF: 3 channel)
Reading: 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) 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) 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) 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: 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) PGM, PPM, and PAM require `maxval` (maximum of 65535)
PAM also uses `tupltype`, though it may be left as default (empty or nil string) PAM also uses `tupltype`, though it may be left as default (empty or nil string)
PFM requires `scale`, and optionally `little_endian` PFM requires `scale`, and optionally `little_endian`
Some syntax differences from the specifications: 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 package netpbm
+7 -7
View File
@@ -12,9 +12,8 @@
CPU feature flags can be tested against `cpu_features`, where applicable, e.g. CPU feature flags can be tested against `cpu_features`, where applicable, e.g.
`if .aes in si.aes { ... }` `if .aes in si.aes { ... }`
*/
//+build ignore Example:
package sysinfo
import "core:fmt" import "core:fmt"
import si "core:sys/info" import si "core:sys/info"
@@ -35,8 +34,8 @@ main :: proc() {
} }
} }
/* - Example Windows output:
Example Windows output:
Odin: dev-2022-09 Odin: dev-2022-09
OS: Windows 10 Professional (version: 20H2), build: 19042.1466 OS: Windows 10 Professional (version: 20H2), build: 19042.1466
OS: OS_Version{ OS: OS_Version{
@@ -53,13 +52,13 @@ main :: proc() {
} }
CPU: AMD Ryzen 7 1800X Eight-Core Processor CPU: AMD Ryzen 7 1800X Eight-Core Processor
RAM: 65469 MiB RAM: 65469 MiB
GPU #0: GPU #0:
Vendor: Advanced Micro Devices, Inc. Vendor: Advanced Micro Devices, Inc.
Model: Radeon RX Vega Model: Radeon RX Vega
VRAM: 8176 MiB VRAM: 8176 MiB
Example macOS output: - Example macOS output:
ODIN: dev-2022-09 ODIN: dev-2022-09
OS: OS_Version{ OS: OS_Version{
platform = "MacOS", platform = "MacOS",
@@ -76,3 +75,4 @@ main :: proc() {
CPU: Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz CPU: Intel(R) Core(TM) i5-7360U CPU @ 2.30GHz
RAM: 8192 MiB RAM: 8192 MiB
*/ */
package sysinfo
+4 -9
View File
@@ -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`. 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(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. - `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. 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. 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. You can also assign it to a loaded catalog after parsing, of course.
Some code examples follow. Example:
*/
/*
```cpp
import "core:fmt" import "core:fmt"
import "core:text/i18n" import "core:text/i18n"
@@ -107,5 +102,5 @@ qt :: proc() {
println("\t 1 =", T("apple_count", "%d apple(s)", 1)) println("\t 1 =", T("apple_count", "%d apple(s)", 1))
println("\t 42 =", T("apple_count", "%d apple(s)", 42)) println("\t 42 =", T("apple_count", "%d apple(s)", 42))
} }
```
*/ */
package i18n
+5 -18
View File
@@ -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{}) tbl := init(&Table{})
padding(tbl, 0, 1) padding(tbl, 0, 1)
row(tbl, "A_LONG_ENUM", "= 54,", "// A comment about A_LONG_ENUM") row(tbl, "A_LONG_ENUM", "= 54,", "// A comment about A_LONG_ENUM")
@@ -17,19 +14,14 @@
} }
io.write_byte(stdio_writer(), '\n') io.write_byte(stdio_writer(), '\n')
} }
```
This outputs: This outputs:
```
A_LONG_ENUM = 54, // A comment about A_LONG_ENUM A_LONG_ENUM = 54, // A comment about A_LONG_ENUM
AN_EVEN_LONGER_ENUM = 1, // A comment about AN_EVEN_LONGER_ENUM AN_EVEN_LONGER_ENUM = 1, // A comment about AN_EVEN_LONGER_ENUM
```
--- **ASCII rendering example:**
ASCII rendering example:
```odin
tbl := init(&Table{}) tbl := init(&Table{})
defer destroy(tbl) defer destroy(tbl)
@@ -69,10 +61,9 @@
write_ascii_table(stdio_writer(), tbl) write_ascii_table(stdio_writer(), tbl)
write_markdown_table(stdio_writer(), tbl) write_markdown_table(stdio_writer(), tbl)
```
This outputs: This outputs:
```
+-----------------------------------------------+ +-----------------------------------------------+
| This is a table caption and it is very long | | This is a table caption and it is very long |
+------------------+-----------------+----------+ +------------------+-----------------+----------+
@@ -82,19 +73,15 @@
| 000000005 | 6.283185 | | | 000000005 | 6.283185 | |
| a | bbb | c | | a | bbb | c |
+------------------+-----------------+----------+ +------------------+-----------------+----------+
```
and and
```
| AAAAAAAAA | B | C | | AAAAAAAAA | B | C |
|:-----------------|:---------------:|---------:| |:-----------------|:---------------:|---------:|
| 123 | foo | | | 123 | foo | |
| 000000005 | 6.283185 | | | 000000005 | 6.283185 | |
| a | bbb | c | | a | bbb | c |
```
respectively. respectively.
*/ */
package text_table package text_table