Documentation
Integrated self-documentation tool can be used to generate Markdown files from Biscuit source files automatically. Documentation text can be attached to a file by //!
comment prefix or to declaration by ///
comment prefix. Such comments will be recognized by the compiler and attached to the proper declaration or file compilation unit. Use -doc
compiler flag followed by a list of files you want to generate documentation for. Documentation output will be written to the out
directory into the current working directory if the --doc-out-dir
is not specified.
Use marker @Incomplete
in the documentation comment to mark it as incomplete. The compiler will warn you about symbols with incomplete documentation during generation.
Documentation rules:
- Only files listed in compiler input are used as generation input (no loaded or imported files are included).
- Documentation is generated from AST; only a parsing pass is performed.
- When the out directory already exists, the compiler will only append new files and override old ones in case of collision.
- Only global and non-private declarations can be documented.
- A declaration name and declaration itself are included automatically.
- A single
md
file is produced for every input source file.
Example of documented print
function:
/// Write string to the standard output (stdout). Format string can include format specifiers `%`
/// which are replaced by corresponding argument value passed in `args`. Value-string conversion is
/// done automatically, we can pass values of any type as an arguments, even structures or arrays.
///
/// The `print` function accepts C-like escape sequences as `\n`, `\t`, `\r`, etc.
///
/// Pointers to `Error` are dereferenced automatically; so the `print` function can print out errors
/// directly.
///
/// Count of printed bytes is returned.
print :: fn (format: string, args: ...) s32 {
buf: [PRINT_MAX_LENGTH]u8 #noinit;
w := _print_impl(buf, format, args);
__os_write(OS_STDOUT, buf.ptr, auto w);
return w;
}
Execution of blc -doc print.bl
will produce following output:
## print
```
print :: fn (format: string, args: ...) s32
```
Write string to the standard output (stdout). Format string can include format specifiers `%`
which are replaced by corresponding argument value passed in `args`. Value-string conversion is
done automatically, we can pass values of any type as an arguments, even structures or arrays.
The `print` function accepts C-like escape sequences as `\n`, `\t`, `\r`, etc.
Pointers to `Error` are dereferenced automatically; so the `print` function can print out errors
directly.
Count of printed bytes is returned.