En esta página

Guidedog / Documentación 0.2.0

odindoc

Package odindoc reads Odin packages by static analysis, with Odin’s own parser (core:odin/parser), and writes the reStructuredText of the Guidedoc odin domain that documents them, as sphinx.ext.autodoc writes the Python domain’s: packages, procedures, procedure groups, types and their fields or enumerators, constants, variables, and foreign imports, each with its doc comment turned into reST.

It never runs the compiler: types are shown as written. A package’s files are read the way Odin builds them for every target at once: file-name suffixes (_windows, _linux_arm64) and #+build tags choose the targets a file builds for, and file-scope when ODIN_OS == ... blocks are evaluated when their conditions are that simple. A declaration made for every target the package builds for is documented once; one made for some targets only says which (see platform.odin).

It is a host library: it reads files through a File_Reader and allocates with the context allocator, freeing nothing itself, so a host runs it in an arena: a Project, the packages it loads, and the lines document returns live until the arena is freed.

Types

odindoc.Arch :: runtime.Odin_Arch_Type

odindoc.Archs :: runtime.Odin_Arch_Types

odindoc.Config :: struct

default_options: []Option

member_order: string

«source» (the default), «alphabetical», «groupwise».

odindoc.Decl :: struct

Decl is a package-level declaration. signature is one line, without attributes, as the odin domain’s directive takes it («clone :: proc(s: string) -> string»).

name: string

kind: Kind

signature: string

attributes: []string

as written, in order: «@(require_results)».

docs: string

private: Private

members: []Member

foreign_lib: string

the library of a foreign block it is declared in.

targets: Targets

availability: string

its targets for people, when not the package’s all.

variant: int

0; 1, 2, … for later declarations of the name that differ.

file: string

base name.

line: int

order: int

in the package: files by name, then position.

odindoc.File_Read :: struct

path: string

text: string

odindoc.File_Reader :: struct

File_Reader reads the files the analysis needs. procedure reads a file; list names the entries of a folder (folders end with «/»). Either may be nil, which uses the file system; a host confines both to its readable roots.

reserve, when set, is asked for the memory parsing a file may take (parse_bound) before the file is parsed; a file it refuses is not parsed (Package.too_large). Odin’s parser does not survive a failed allocation, so a host whose allocator can refuse reserves the bound ahead, and its allocator then serves the parse from what was reserved.

procedure: proc(user: rawptr, path: string) -> (string, bool)

list: proc(user: rawptr, dir: string) -> ([]string, bool)

reserve: proc(user: rawptr, bytes: int) -> bool

user: rawptr

odindoc.Import :: struct

Import is a package another package imports: the name it is used by in the source (its alias) and the id of the package it names.

alias: string

id: string

odindoc.Kind :: enum u8

Proc

Proc_Group

Struct

Union

Enum

Bit_Set

Bit_Field

Type

Const

Var

Foreign_Import

odindoc.Member :: struct

name: string

kind: Member_Kind

signature: string

docs: string

the comment above it and the one after it on its line.

odindoc.Member_Kind :: enum u8

Field

of a struct: «[using ]name: T[ tag]».

Enumerator

of an enum: «Name[ = value]».

Bit_Field

of a bit_field: «name: T | bits».

odindoc.Message :: struct

severity: Severity

code: string

title: string

text: string

hint: string

odindoc.OS :: runtime.Odin_OS_Type

odindoc.Option :: struct

name: string

value: string

odindoc.Package :: struct

Package is an analysed package. doc is its package comment (from doc.odin first, then the first file by name that has one) with comment markers stripped; synopsis is that comment’s first sentence.

id: string

name: string

dir: string

doc: string

synopsis: string

decls: []Decl

imports: []Import

targets: Targets

every target some file of the package builds for.

platform: string

targets shown for people; «» when it builds for all.

files: []string

the package’s files that were read, sorted.

errors: int

syntax errors the parser reported.

too_deep: [dynamic]string

files nested too deeply to parse (nesting.odin).

too_large: [dynamic]string

files whose parse_bound the reader refused.

odindoc.Package_Ref :: struct

id: string

dir: string

odindoc.Private :: enum u8

Public

Package

@(private), or a #+private file.

File

@(private=»file»), or a #+private file file.

odindoc.Project :: struct

roots: []Root

reader: File_Reader

files: [dynamic]File_Read

every file read, for the host’s dependencies.

packages: map[string]^Package

loaded packages by id; nil for one that failed.

odindoc.Request :: struct

directive: string

«odin:autopackage», «odin:autoproc», …

argument: string

options: []Option

current: string

the reader’s current odin package, or «».

odindoc.Result :: struct

lines: [dynamic]string

messages: [dynamic]Message

odindoc.Root :: struct

Root is a folder holding packages. Without a collection, a package’s id is its path relative to dir («readers/sphinx»), and dir’s own package is named by dir’s base name; with one, ids are import paths in that collection («core:fmt»).

dir: string

collection: string

odindoc.Severity :: enum u8

Note

Warning

Error

odindoc.Targets :: [OS]Archs

Targets is a set of (os, arch) pairs: per system, its architectures.

Procedures

odindoc.document :: proc(p: ^Project, config: ^Config, request: Request) -> Result

document runs one autodoc directive (request.directive, «odin:autopackage» and the others, with its argument and options over config’s defaults) and returns the reStructuredText lines it generates, with any messages: an unknown directive, option, package, or name is an Error message and no lines, never a panic. Packages are loaded through p as needed. The result lives in the context arena.

odindoc.init :: proc(p: ^Project, roots: []Root, reader := File_Reader{})

init starts a project over roots, reading through reader (the file system when it is zero). The project and everything it loads live in the context arena.

odindoc.list_packages :: proc(p: ^Project) -> []Package_Ref

list_packages lists every folder below the roots that holds a package, by id.

odindoc.load :: proc(p: ^Project, id: string) -> (^Package, bool)

load analyses the package with an id, once; later calls return the same package, which the project keeps. It is false when no root holds a package with that id.

odindoc.parse_bound :: proc(n: int) -> int

parse_bound is the memory parsing a file of n bytes may take.

Constants

odindoc.PARSE_BASE_BYTES :: 256 << 10

PARSE_BASE_BYTES is what the parser allocates for any file, and an arena block’s room.

odindoc.PARSE_BYTES_PER_BYTE :: 256

PARSE_BYTES_PER_BYTE bounds what Odin’s parser allocates, with the build tags read after it, for each byte of a file it parses. Its tree takes 20 to 30 bytes for each byte of ordinary code, and up to about 170 for the densest input measured: long operator chains, runs of semicolons, and one-character list items (parse_bounds_hold). The bound counts every growth of a list as a new allocation, as an arena that cannot grow it in place makes it.