Module v.doc | Standard Library documentation

Aliases

This section is empty.

Constants

pub const should_sort = os.getenv_opt('VDOC_SORT') or { 'true' }.bool()

Sum types

This section is empty.

Functions

fn ast_comment_to_doc_comment(ast_node v.ast.Comment) DocComment

ast_comment_to_doc_comment converts an ast.Comment node type to a DocComment

fn ast_comments_to_doc_comments(ast_nodes []v.ast.Comment) []DocComment

ast_comments_to_doc_comments converts an array of ast.Comment nodes to an array of DocComment nodes

fn generate(input_path string, pub_only bool, with_comments bool, platform Platform, filter_symbol_names []string) !Doc

generate documents a certain file directory and returns an instance of Doc if it is successful. Otherwise, it will throw an error.

fn generate_from_mod(module_name string, pub_only bool, with_comments bool) !Doc

generate_from_mod generates a documentation from a specific module.

fn generate_with_pos(input_path string, filename string, pos int) !Doc

generate_with_pos has the same function as the generate function but accepts an offset-based position and enables the comments by default.

fn lookup_module(mod string) !string

lookup_module returns the result of the lookup_module_with_path but with the current directory as the provided base lookup path.

fn lookup_module_with_path(mod string, base_path string) !string

lookup_module_with_path looks up the path of a given module name.

Throws an error if the module was not found.

fn merge_comments(comments []v.ast.Comment) string

merge_comments merges all the comment contents into a single text.

fn merge_doc_comments(comments []DocComment) string

merge_doc_comments merges all the comments starting from the last up to the first item of the array.

fn new(input_path string) Doc

new creates a new instance of a Doc struct.

fn new_vdoc_preferences() &v.pref.Preferences

new_vdoc_preferences creates a new instance of pref.Preferences tailored for v.doc.

fn platform_from_filename(filename string) Platform

fn platform_from_string(platform_str string) !Platform

copy of pref.os_from_string

fn (nodes []DocNode) find(symname string) !DocNode

fn (mut nodes &[]DocNode) sort_by_name()

sort_by_name sorts the array based on the symbol names.

fn (mut nodes &[]DocNode) sort_by_kind()

sort_by_kind sorts the array based on the symbol kind.

fn (cnts map[string]DocNode) arr() []DocNode

arr() converts the map into an array of DocNode.

Structs

pub struct DocComment {
pub mut:
	text     string // Raw text content of the comment, excluding the comment token chars ('//, /*, */')
	is_multi bool   // Is a block / multi-line comment
	pos      token.Pos
}

fn (dc DocComment) is_example() bool

is_example returns true if the contents of this comment is an inline doc example.

The current convention is '// Example: '

fn (dc DocComment) example() string

example returns the content of the inline example body

fn (dc DocComment) is_multi_line_example() bool

is_multi_line_example returns true if an example line has no inline code

fn (dc DocComment) has_triple_backtick() bool

has_triple_backtick returns true if the comment starts or ends a markdown code block

pub struct Doc {
pub mut:
	prefs     &pref.Preferences = new_vdoc_preferences()
	base_path string
	table     &ast.Table      = ast.new_table()
	checker   checker.Checker = checker.Checker{
		table: 0
		pref: 0
	}
	fmt                 fmt.Fmt
	filename            string
	pos                 int
	pub_only            bool = true
	with_comments       bool = true
	with_pos            bool
	with_head           bool = true
	is_vlib             bool
	time_generated      time.Time
	head                DocNode
	contents            map[string]DocNode
	scoped_contents     map[string]DocNode
	parent_mod_name     string
	orig_mod_name       string
	extract_vars        bool
	filter_symbol_names []string
	common_symbols      []string
	platform            Platform
}

fn (mut d &Doc) stmt(stmt v.ast.Stmt, filename string) !DocNode

stmt reads the data of an ast.Stmt node and returns a DocNode.

An option error is thrown if the symbol is not exposed to the public (when pub_only is enabled) or the content's of the AST node is empty.

fn (mut d &Doc) file_ast(file_ast v.ast.File) map[string]DocNode

file_ast reads the contents of ast.File and returns a map of DocNodes.

fn (mut d &Doc) file_ast_with_pos(file_ast v.ast.File, pos int) map[string]DocNode

file_ast_with_pos has the same function as the file_ast but instead returns a list of variables in a given offset-based position.

fn (mut d &Doc) generate() !

generate is a Doc method that will start documentation process based on a file path provided.

fn (mut d &Doc) file_asts(file_asts []v.ast.File) !

file_asts has the same function as the file_ast function but accepts an array of ast.File and throws an error if necessary.

fn (mut d &Doc) stmt_signature(stmt v.ast.Stmt) string

stmt_signature returns the signature of a given ast.Stmt node.

fn (d &Doc) stmt_name(stmt v.ast.Stmt) string

stmt_name returns the name of a given ast.Stmt node.

fn (d &Doc) stmt_pub(stmt v.ast.Stmt) bool

stmt_pub returns a boolean if a given ast.Stmt node is exposed to the public.

fn (mut d &Doc) type_to_str(typ v.ast.Type) string

type_to_str is a wrapper function around fmt.ast.type_to_str.

fn (mut d &Doc) expr_typ_to_string(ex v.ast.Expr) string

expr_typ_to_string has the same function as Doc.typ_to_str but for ast.Expr nodes. The checker will check first the node and it executes the type_to_str method.

pub struct DocNode {
pub mut:
	name        string
	content     string
	comments    []DocComment
	pos         token.Pos
	file_path   string
	kind        SymbolKind
	tags        []string
	parent_name string
	return_type string
	children    []DocNode
	attrs       map[string]string [json: attributes]
	from_scope  bool
	is_pub      bool              [json: public]
	platform    Platform
}

fn (dc &DocNode) merge_comments() string

merge_comments returns a string with the combined contents of DocNode.comments.

fn (dc &DocNode) merge_comments_without_examples() string

merge_comments_without_examples returns a string with the combined contents of DocNode.comments - excluding any examples.

fn (dn &DocNode) examples() []string

examples returns a []string containing examples parsed from DocNode.comments.

Interfaces

This section is empty.

Enums

pub enum SymbolKind {
	none_
	const_group
	constant
	variable
	function
	method
	interface_
	typedef
	enum_
	enum_field
	struct_
	struct_field
}

SymbolKind categorizes the symbols it documents.

The names are intentionally not in order as a guide when sorting the nodes.

fn (sk SymbolKind) str() string

pub enum Platform {
	auto
	ios
	macos
	linux
	windows
	freebsd
	openbsd
	netbsd
	dragonfly
	js // for interoperability in prefs.OS
	android
	termux // like android, but note that termux is running on devices natively, not cross compiling from other platforms
	solaris
	serenity
	vinix
	haiku
	raw
	cross // TODO: add functionality for v doc -os cross whenever possible
}

Module v.doc stdlib

Dependencies defined in v.mod

Imports

Standard Library

Imported by

Aliases

Constants

#constant should_sort

Sum types

Functions

#fn ast_comment_to_doc_comment

#fn ast_comments_to_doc_comments

#fn generate

#fn generate_from_mod

#fn generate_with_pos

#fn lookup_module

#fn lookup_module_with_path

#fn merge_comments

#fn merge_doc_comments

#fn new

#fn new_vdoc_preferences

#fn platform_from_filename

#fn platform_from_string

#fn ([]DocNode) find

#fn (&[]DocNode) sort_by_name

#fn (&[]DocNode) sort_by_kind

#fn (map[string]DocNode) arr

Structs

#struct DocComment

#fn (DocComment) is_example

#fn (DocComment) example

#fn (DocComment) is_multi_line_example

#fn (DocComment) has_triple_backtick

#struct Doc

#fn (&Doc) stmt

#fn (&Doc) file_ast

#fn (&Doc) file_ast_with_pos

#fn (&Doc) generate

#fn (&Doc) file_asts

#fn (&Doc) stmt_signature

#fn (&Doc) stmt_name

#fn (&Doc) stmt_pub

#fn (&Doc) type_to_str

#fn (&Doc) expr_typ_to_string

#struct DocNode

#fn (&DocNode) merge_comments

#fn (&DocNode) merge_comments_without_examples

#fn (&DocNode) examples

Interfaces

Enums

#enum SymbolKind

#fn (SymbolKind) str

#enum Platform

Module `v.doc` stdlib

Dependencies defined in `v.mod`

#constant `should_sort`

#fn `ast_comment_to_doc_comment`

#fn `ast_comments_to_doc_comments`

#fn `generate`

#fn `generate_from_mod`

#fn `generate_with_pos`

#fn `lookup_module`

#fn `lookup_module_with_path`

#fn `merge_comments`

#fn `merge_doc_comments`

#fn `new`

#fn `new_vdoc_preferences`

#fn `platform_from_filename`

#fn `platform_from_string`

#fn `([]DocNode) find`

#fn `(&[]DocNode) sort_by_name`

#fn `(&[]DocNode) sort_by_kind`

#fn `(map[string]DocNode) arr`

#struct `DocComment`

#fn `(DocComment) is_example`

#fn `(DocComment) example`

#fn `(DocComment) is_multi_line_example`

#fn `(DocComment) has_triple_backtick`

#struct `Doc`

#fn `(&Doc) stmt`

#fn `(&Doc) file_ast`

#fn `(&Doc) file_ast_with_pos`

#fn `(&Doc) generate`

#fn `(&Doc) file_asts`

#fn `(&Doc) stmt_signature`

#fn `(&Doc) stmt_name`

#fn `(&Doc) stmt_pub`

#fn `(&Doc) type_to_str`

#fn `(&Doc) expr_typ_to_string`

#struct `DocNode`

#fn `(&DocNode) merge_comments`

#fn `(&DocNode) merge_comments_without_examples`

#fn `(&DocNode) examples`

#enum `SymbolKind`

#fn `(SymbolKind) str`

#enum `Platform`