mirror/v
1
0
Fork 0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00
Code Issues Projects Releases Wiki Activity

vdoc: use maps, enum-based categorization; fixes (#6659)

Browse Source
This commit is contained in:
Ned Palacios
2020-10-21 16:26:33 +08:00
committed by GitHub
parent 0e56b96bda
commit 5b1ab3b0bb
4 changed files with 305 additions and 299 deletions
Download Patch File Download Diff File Expand all files Collapse all files

319
vlib/v/doc/doc.v
View File

@@ -13,27 +13,42 @@ import v.table
import v.token
import v.util
// intentionally in order as a guide when arranging the docnodes
pub enum SymbolKind {
none_
typedef
interface_
const_group
const_field
enum_
variable
function
method
struct_
}
pub struct Doc {
prefs &pref.Preferences
prefs &pref.Preferences = new_vdoc_preferences()
pub mut:
input_path string
table &table.Table = &table.Table{}
checker checker.Checker = checker.Checker{
input_path string
table &table.Table = &table.Table{}
checker checker.Checker = checker.Checker{
table: 0
cur_fn: 0
pref: 0
}
pub_only bool = true
head DocNode
with_comments bool = true
contents []DocNode
fmt fmt.Fmt
time_generated time.Time
with_pos bool
with_head bool = true
filename string
pos int
is_vlib bool
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
}
pub struct DocPos {
@@ -45,12 +60,17 @@ pub:
pub struct DocNode {
pub mut:
name string
content string
comment string
pos DocPos = DocPos{-1, -1, 0}
file_path string
attrs map[string]string
name string
content string
comment string
pos DocPos = DocPos{-1, -1, 0}
file_path string
kind SymbolKind
deprecated bool
parent_name string
children []DocNode
attrs map[string]string
from_scope bool
}
pub fn merge_comments(comments []ast.Comment) string {
@@ -136,13 +156,13 @@ pub fn (mut d Doc) get_signature(stmt ast.Stmt, file &ast.File) string {
}
pub fn (d Doc) get_pos(stmt ast.Stmt) token.Position {
match stmt {
ast.FnDecl, ast.StructDecl, ast.EnumDecl, ast.InterfaceDecl, ast.ConstDecl { return stmt.pos }
else { return token.Position{} }
if stmt is ast.InterfaceDecl {
return stmt.pos
}
return stmt.position()
}
pub fn (d Doc) get_type_name(decl ast.TypeDecl) string {
pub fn get_type_decl_name(decl ast.TypeDecl) string {
match decl {
ast.SumTypeDecl, ast.FnTypeDecl, ast.AliasTypeDecl { return decl.name }
}
@@ -151,9 +171,9 @@ pub fn (d Doc) get_type_name(decl ast.TypeDecl) string {
pub fn (d Doc) get_name(stmt ast.Stmt) string {
match stmt {
ast.FnDecl, ast.StructDecl, ast.EnumDecl, ast.InterfaceDecl { return stmt.name }
ast.TypeDecl { return d.get_type_name(stmt) }
ast.ConstDecl { return 'Constants' }
else { return typeof(stmt) }
ast.TypeDecl { return get_type_decl_name(stmt) }
ast.ConstDecl { return '' } // leave it blank
else { return '' }
}
}
@@ -168,10 +188,9 @@ pub fn new_vdoc_preferences() &pref.Preferences {
pub fn new(input_path string) Doc {
mut d := Doc{
input_path: os.real_path(input_path)
prefs: new_vdoc_preferences()
table: table.new_table()
head: DocNode{}
contents: []DocNode{}
contents: map[string]DocNode{}
time_generated: time.now()
}
d.fmt = fmt.Fmt{
@@ -187,8 +206,20 @@ pub fn (mut nodes []DocNode) sort_by_name() {
nodes.sort_with_compare(compare_nodes_by_name)
}
pub fn (mut nodes []DocNode) sort_by_category() {
nodes.sort_with_compare(compare_nodes_by_category)
pub fn (mut nodes []DocNode) sort_by_kind() {
nodes.sort_with_compare(compare_nodes_by_kind)
}
fn compare_nodes_by_kind(a &DocNode, b &DocNode) int {
ak := int((*a).kind)
bk := int((*b).kind)
if ak < bk {
return -1
}
if ak > bk {
return 1
}
return 0
}
fn compare_nodes_by_name(a &DocNode, b &DocNode) int {
@@ -197,39 +228,11 @@ fn compare_nodes_by_name(a &DocNode, b &DocNode) int {
return compare_strings(al, bl)
}
fn compare_nodes_by_category(a &DocNode, b &DocNode) int {
al := a.attrs['category']
bl := b.attrs['category']
return compare_strings(al, bl)
}
pub fn (nodes []DocNode) index_by_name(node_name string) int {
for i, node in nodes {
if node.name != node_name {
continue
}
return i
}
return -1
}
pub fn (nodes []DocNode) find_children_of(parent string) []DocNode {
return nodes.find_nodes_with_attr('parent', parent)
}
pub fn (nodes []DocNode) find_nodes_with_attr(attr_name string, value string) []DocNode {
mut subgroup := []DocNode{}
if attr_name.len == 0 {
return subgroup
}
for node in nodes {
if !node.attrs.exists(attr_name) || node.attrs[attr_name] != value {
continue
}
subgroup << node
}
subgroup.sort_by_name()
return subgroup
pub fn (cnts map[string]DocNode) arr() []DocNode {
mut contents := cnts.keys().map(cnts[it])
contents.sort_by_name()
contents.sort_by_kind()
return contents
}
// get_parent_mod - return the parent mod name, in dot format.
@@ -250,9 +253,9 @@ fn get_parent_mod(input_dir string) ?string {
}
}
base_dir := os.dir(input_dir)
input_dir_name := os.file_name(input_dir)
input_dir_name := os.file_name(base_dir)
prefs := new_vdoc_preferences()
fentries := os.ls(input_dir) or {
fentries := os.ls(base_dir) or {
[]string{}
}
files := fentries.filter(!os.is_dir(it))
@@ -260,7 +263,7 @@ fn get_parent_mod(input_dir string) ?string {
// the top level is reached, no point in climbing up further
return ''
}
v_files := prefs.should_compile_filtered_files(input_dir, files)
v_files := prefs.should_compile_filtered_files(base_dir, files)
if v_files.len == 0 {
parent_mod := get_parent_mod(base_dir) or {
return input_dir_name
@@ -279,17 +282,17 @@ fn get_parent_mod(input_dir string) ?string {
return ''
}
parent_mod := get_parent_mod(base_dir) or {
return error(err)
return input_dir_name
}
if parent_mod.len > 0 {
return parent_mod
return '${parent_mod}.$file_ast.mod.name'
}
return file_ast.mod.name
}
pub fn (mut d Doc) generate_from_ast(file_ast ast.File, orig_mod_name string) []DocNode {
mut const_idx := -1
mut contents := []DocNode{}
pub fn (mut d Doc) generate_from_ast(file_ast ast.File) map[string]DocNode {
mut contents := map[string]DocNode{}
orig_mod_name := file_ast.mod.name
stmts := file_ast.stmts
d.fmt.file = file_ast
d.fmt.set_current_module_name(orig_mod_name)
@@ -364,80 +367,82 @@ pub fn (mut d Doc) generate_from_ast(file_ast ast.File, orig_mod_name string) []
}
match stmt {
ast.ConstDecl {
if const_idx == -1 {
const_idx = sidx
} else {
node.attrs['parent'] = 'Constants'
}
node.attrs['category'] = 'Constants'
}
ast.EnumDecl {
node.attrs['category'] = 'Enums'
}
ast.InterfaceDecl {
node.attrs['category'] = 'Interfaces'
}
ast.StructDecl {
node.attrs['category'] = 'Structs'
}
ast.TypeDecl {
node.attrs['category'] = 'Typedefs'
}
ast.FnDecl {
if stmt.is_deprecated {
continue
}
if stmt.receiver.typ != 0 {
node.attrs['parent'] = d.fmt.table.type_to_str(stmt.receiver.typ).trim_left('&')
p_idx := contents.index_by_name(node.attrs['parent'])
if p_idx == -1 && node.attrs['parent'] != 'void' {
contents << DocNode{
name: node.attrs['parent']
content: ''
comment: ''
attrs: {
'category': 'Structs'
}
}
node.kind = .const_group
node.parent_name = 'Constants'
if node.parent_name !in contents {
contents[node.parent_name] = DocNode{
name: 'Constants'
kind: .const_group
}
}
node.attrs['category'] = if node.attrs['parent'] in ['void', ''] || !node.attrs.exists('parent') { 'Functions' } else { 'Methods' }
}
ast.EnumDecl {
node.kind = .enum_
}
ast.InterfaceDecl {
node.kind = .interface_
}
ast.StructDecl {
node.kind = .struct_
}
ast.TypeDecl {
node.kind = .typedef
}
ast.FnDecl {
node.deprecated = stmt.is_deprecated
node.kind = .function
if stmt.receiver.typ !in [0, 1] {
method_parent := d.fmt.table.type_to_str(stmt.receiver.typ).trim_left('&')
if method_parent != 'void' && method_parent !in contents {
contents[method_parent] = DocNode{
name: method_parent
kind: .none_
}
}
node.kind = .method
node.parent_name = method_parent
}
}
else {}
}
contents << node
if d.with_comments && (prev_comments.len > 0) {
last_comment := contents[contents.len - 1].comment
cmt := last_comment + '\n' + get_comment_block_right_before(prev_comments)
contents[contents.len - 1].comment = cmt
// last_comment := contents[contents.len - 1].comment
// cmt := last_comment + '\n' + get_comment_block_right_before(prev_comments)
cmt := get_comment_block_right_before(prev_comments)
node.comment = cmt
}
prev_comments = []
if node.parent_name.len > 0 {
parent_name := node.parent_name
if node.parent_name == 'Constants' {
node.parent_name = ''
}
contents[parent_name].children << node
} else {
contents[node.name] = node
}
}
d.fmt.mod2alias = map[string]string{}
return contents
}
pub fn (mut d Doc) generate_from_ast_with_pos(file_ast ast.File, pos int) []DocNode {
pub fn (mut d Doc) generate_from_ast_with_pos(file_ast ast.File, pos int) map[string]DocNode {
lscope := file_ast.scope.innermost(pos)
mut contents := []DocNode{}
mut contents := map[string]DocNode{}
for name, val in lscope.objects {
if val !is ast.Var {
continue
}
vr_data := val as ast.Var
vr_expr := vr_data.expr
l_node := DocNode{
name: name
content: ''
comment: ''
pos: convert_pos(file_ast.path, vr_data.pos)
file_path: file_ast.path
attrs: {
'category': 'Variable'
'return_type': d.expr_typ_to_string(vr_expr)
'local': 'true'
}
from_scope: true
kind: .variable
parent_name: d.expr_typ_to_string(vr_data.expr)
}
contents << l_node
contents[l_node.name] = l_node
}
return contents
}
@@ -459,30 +464,27 @@ fn (mut d Doc) generate() ?Doc {
return error_with_code('vdoc: No valid V files were found.', 1)
}
// parse files
mut file_asts := []ast.File{}
// TODO: remove later for vlib
comments_mode := if d.with_comments { scanner.CommentsMode.toplevel_comments } else { scanner.CommentsMode.skip_comments }
mut comments_mode := scanner.CommentsMode.skip_comments
if d.with_comments {
comments_mode = .toplevel_comments
}
global_scope := &ast.Scope{
parent: 0
}
mut parent_mod_name := ''
mut fname_has_set := false
for file in v_files {
file_ast := parser.parse_file(file, d.table, comments_mode, d.prefs, &ast.Scope{
parent: 0
})
mut orig_mod_name := ''
for i, file in v_files {
file_ast := parser.parse_file(file, d.table, comments_mode, d.prefs, global_scope)
if d.filename.len > 0 && d.filename in file && !fname_has_set {
d.filename = file
fname_has_set = true
}
file_asts << file_ast
}
mut module_name := ''
mut parent_mod_name := ''
mut orig_mod_name := ''
for i, file_ast in file_asts {
d.checker.check(file_ast)
if i == 0 {
parent_mod_name = get_parent_mod(base_path) or {
''
}
module_name = file_ast.mod.name
mut module_name := file_ast.mod.name
orig_mod_name = module_name
if module_name != 'main' && parent_mod_name.len > 0 {
module_name = parent_mod_name + '.' + module_name
@@ -491,21 +493,27 @@ fn (mut d Doc) generate() ?Doc {
d.head = DocNode{
name: module_name
content: 'module $module_name'
comment: ''
kind: .none_
}
}
} else if file_ast.mod.name != orig_mod_name {
continue
}
d.contents << d.generate_from_ast(file_ast, orig_mod_name)
if file_ast.path == d.filename {
d.contents << d.generate_from_ast_with_pos(file_ast, d.pos)
d.checker.check(file_ast)
d.scoped_contents = d.generate_from_ast_with_pos(file_ast, d.pos)
}
contents := d.generate_from_ast(file_ast)
for name, node in contents {
if name in d.contents && (d.contents[name].kind != .none_ || node.kind == .none_) {
d.contents[name].children << node.children
d.contents[name].children.sort_by_name()
continue
}
d.contents[name] = node
}
d.fmt.mod2alias = map[string]string{}
}
d.time_generated = time.now()
d.contents.sort_by_name()
d.contents.sort_by_category()
return *d
}
@@ -525,3 +533,24 @@ pub fn generate(input_path string, pub_only bool, with_comments bool) ?Doc {
doc.with_comments = with_comments
return doc.generate()
}
pub fn lookup_module(mod string) ?string {
mod_path := mod.replace('.', os.path_separator)
compile_dir := os.real_path(os.dir('.'))
modules_dir := os.join_path(compile_dir, 'modules', mod_path)
vlib_path := os.join_path(os.dir(@VEXE), 'vlib', mod_path)
vmodules_path := os.join_path(os.home_dir(), '.vmodules', mod_path)
paths := [modules_dir, vlib_path, vmodules_path]
for path in paths {
if !os.exists(path) || os.is_dir_empty(path) {
continue
}
return path
}
return error('module "$mod" not found.')
}
pub fn generate_from_mod(module_name string, pub_only bool, with_comments bool) ?Doc {
mod_path := lookup_module(module_name) ?
return generate(mod_path, pub_only, with_comments)
}

26
vlib/v/doc/doc_test.v
View File

@@ -1,9 +1,19 @@
// import v.table
// import v.doc
// import v.pref
// fn test_vdoc() {
// mut prefs := &pref.Preferences{}
// prefs.fill_with_defaults()
// table := table.new_table()
// println(doc.doc('net', table, prefs))
// }
import v.doc
import v.parser
// fn test_generate_with_pos() {}
// fn test_generate() {}
// fn test_generate_from_ast() {}
fn test_generate_from_mod() {
nested_mod_name := 'net.http.chunked'
nested_mod_doc := doc.generate_from_mod(nested_mod_name, false, true) or {
eprintln(err)
assert false
doc.Doc{}
}
assert nested_mod_doc.head.name == nested_mod_name
assert nested_mod_doc.head.content == 'module $nested_mod_name'
assert nested_mod_doc.contents.len == 3
assert nested_mod_doc.contents['ChunkScanner'].children.len == 3
}