v.doc #

fn ast_comment_to_doc_comment(ast_node 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 []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 []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() &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) arrange()

arrange sorts the DocNodes based on their symbols and names.

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

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

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
	plan9
	vinix
	haiku
	raw
	cross // TODO: add functionality for v doc -cross whenever possible
}

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

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: unsafe { nil }
		pref:  unsafe { nil }
	}
	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) expr_typ_to_string(mut expr 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.

fn (mut d Doc) file_ast(mut file_ast 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(mut file_ast 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) file_asts(mut file_asts []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) generate() !

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

fn (mut d Doc) stmt(mut stmt 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 (d Doc) stmt_name(stmt ast.Stmt) string

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

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

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

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

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

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

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

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

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 (dn DocNode) examples() []string

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

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.