From 5b1ab3b0bb956973284ceffbad31e737eee15087 Mon Sep 17 00:00:00 2001
From: Ned Palacios <npdoesmc@gmail.com>
Date: Wed, 21 Oct 2020 16:26:33 +0800
Subject: [PATCH] vdoc: use maps, enum-based categorization; fixes  (#6659)

---
 cmd/tools/vdoc-resources/doc.css |   8 +-
 cmd/tools/vdoc.v                 | 251 ++++++++++--------------
 vlib/v/doc/doc.v                 | 319 +++++++++++++++++--------------
 vlib/v/doc/doc_test.v            |  26 ++-
 4 files changed, 305 insertions(+), 299 deletions(-)

diff --git a/cmd/tools/vdoc-resources/doc.css b/cmd/tools/vdoc-resources/doc.css
index 657cd92c26..c8c389eb78 100644
--- a/cmd/tools/vdoc-resources/doc.css
+++ b/cmd/tools/vdoc-resources/doc.css
@@ -274,6 +274,9 @@ body {
 	word-break: break-all; /* IE11 */
 	word-break: break-word;
 }
+.doc-content > .doc-node.const:nth-child(2) {
+  padding-bottom: 0 !important;
+}
 .doc-content > .doc-node.const:not(:first-child) {
 	padding-top: 4rem;
 }
@@ -417,7 +420,7 @@ pre, code, pre code {
   background-color: #edf2f7;
   background-color: var(--code-background-color);
   border-radius: 0.25rem;
-}	
+}
 pre code {
   direction: ltr;
   text-align: left;
@@ -556,6 +559,9 @@ pre {
 	.doc-nav .content.hidden {
 		display: flex;
 	}
+	.doc-content > .doc-node.const:nth-child(2) {
+		padding-bottom: 0 !important;
+	}
 	.doc-content > .doc-node.const:not(:first-child) {
 		padding-top: 0;
 	}
diff --git a/cmd/tools/vdoc.v b/cmd/tools/vdoc.v
index ece7982303..9d085f331b 100644
--- a/cmd/tools/vdoc.v
+++ b/cmd/tools/vdoc.v
@@ -15,6 +15,7 @@ import v.table
 import v.token
 import v.vmod
 import v.pref
+import json
 
 enum HighlightTokenTyp {
 	unone
@@ -124,10 +125,12 @@ struct ParallelDoc {
 	i int
 }
 
+[inline]
 fn slug(title string) string {
 	return title.replace(' ', '-')
 }
 
+[inline]
 fn open_url(url string) {
 	$if windows {
 		os.system('start $url')
@@ -149,7 +152,6 @@ fn (mut cfg DocConfig) serve_html() {
 		exit(1)
 	}
 	def_name := docs.keys()[0]
-	//
 	server_url := 'http://localhost:' + cfg.server_port.str()
 	server := net.listen(cfg.server_port) or {
 		panic(err)
@@ -268,7 +270,9 @@ fn js_compress(str string) string {
 		}
 		js.write(trimmed)
 	}
-	return js.str()
+	js_str := js.str()
+	js.free()
+	return js_str
 }
 
 fn escape(str string) string {
@@ -278,29 +282,9 @@ fn escape(str string) string {
 fn (cfg DocConfig) gen_json(idx int) string {
 	dcs := cfg.docs[idx]
 	mut jw := strings.new_builder(200)
-	jw.write('{"module_name":"$dcs.head.name","description":"${escape(dcs.head.comment)}","contents":[')
-	for i, cn in dcs.contents {
-		name := cn.name.all_after(dcs.head.name)
-		jw.write('{"name":"$name","signature":"${escape(cn.content)}",')
-		jw.write('"description":"${escape(cn.comment)}",')
-		jw.write('"position":[$cn.pos.line,$cn.pos.col,$cn.pos.len],')
-		jw.write('"file_path":"$cn.file_path",')
-		jw.write('"attrs":{')
-		mut j := 0
-		for n, v in cn.attrs {
-			jw.write('"$n":"$v"')
-			if j < cn.attrs.len - 1 {
-				jw.write(',')
-			}
-			j++
-		}
-		jw.write('}')
-		jw.write('}')
-		if i < dcs.contents.len - 1 {
-			jw.write(',')
-		}
-	}
-	jw.write('],"generator":"vdoc","time_generated":"$dcs.time_generated.str()"}')
+	jw.write('{"module_name":"$dcs.head.name","description":"${escape(dcs.head.comment)}","contents":')
+	jw.write(json.encode(dcs.contents.keys().map(dcs.contents[it])))
+	jw.write(',"generator":"vdoc","time_generated":"$dcs.time_generated.str()"}')
 	return jw.str()
 }
 
@@ -392,27 +376,27 @@ fn doc_node_html(dd doc.DocNode, link string, head bool, tb &table.Table) string
 	head_tag := if head { 'h1' } else { 'h2' }
 	md_content := markdown.to_html(dd.comment)
 	hlighted_code := html_highlight(dd.content, tb)
-	node_class := if dd.name == 'Constants' { ' const' } else { '' }
-	sym_name := if dd.attrs.exists('parent') && dd.attrs['parent'] !in ['void', '', 'Constants'] { dd.attrs['parent'] +
-			'.' + dd.name } else { dd.name }
+	node_class := if dd.kind == .const_group { ' const' } else { '' }
+	sym_name := if dd.parent_name.len > 0 && dd.parent_name != 'void' { dd.parent_name + '.' + dd.name } else { dd.name }
 	node_id := slug(sym_name)
 	hash_link := if !head { ' <a href="#$node_id">#</a>' } else { '' }
 	dnw.writeln('<section id="$node_id" class="doc-node$node_class">')
-	if dd.name != 'README' && dd.attrs['parent'] != 'Constants' {
+	if dd.name.len > 0 {
 		dnw.write('<div class="title"><$head_tag>$sym_name$hash_link</$head_tag>')
 		if link.len != 0 {
 			dnw.write('<a class="link" rel="noreferrer" target="_blank" href="$link">$link_svg</a>')
 		}
 		dnw.write('</div>')
 	}
-	if head {
-		dnw.write(md_content)
-	} else {
+	if !head && dd.content.len > 0 {
 		dnw.writeln('<pre class="signature"><code>$hlighted_code</code></pre>')
-		dnw.writeln(md_content)
 	}
-	dnw.writeln('</section>')
-	return dnw.str()
+	dnw.writeln('$md_content\n</section>')
+	dnw_str := dnw.str()
+	defer {
+		dnw.free()
+	}
+	return dnw_str
 }
 
 fn (cfg DocConfig) readme_idx() int {
@@ -426,12 +410,11 @@ fn (cfg DocConfig) readme_idx() int {
 }
 
 fn write_toc(cn doc.DocNode, nodes []doc.DocNode, mut toc strings.Builder) {
-	toc_slug := if cn.content.len == 0 { '' } else { slug(cn.name) }
+	toc_slug := if cn.name.len == 0 { '' } else { slug(cn.name) }
 	toc.write('<li class="open"><a href="#$toc_slug">$cn.name</a>')
-	children := nodes.find_children_of(cn.name)
 	if cn.name != 'Constants' {
 		toc.writeln('        <ul>')
-		for child in children {
+		for child in cn.children {
 			cname := cn.name + '.' + child.name
 			toc.writeln('<li><a href="#${slug(cname)}">$child.name</a></li>')
 		}
@@ -444,11 +427,10 @@ fn (cfg DocConfig) write_content(cn &doc.DocNode, dcs &doc.Doc, mut hw strings.B
 	base_dir := os.dir(os.real_path(cfg.input_path))
 	file_path_name := if cfg.is_multi { cn.file_path.replace('$base_dir/', '') } else { os.file_name(cn.file_path) }
 	src_link := get_src_link(cfg.manifest.repo_url, file_path_name, cn.pos.line)
-	children := dcs.contents.find_children_of(cn.name)
-	if cn.content.len != 0 {
+	if cn.content.len != 0 || (cn.name == 'Constants') {
 		hw.write(doc_node_html(cn, src_link, false, dcs.table))
 	}
-	for child in children {
+	for child in cn.children {
 		child_file_path_name := child.file_path.replace('$base_dir/', '')
 		child_src_link := get_src_link(cfg.manifest.repo_url, child_file_path_name, child.pos.line)
 		hw.write(doc_node_html(child, child_src_link, false, dcs.table))
@@ -456,18 +438,16 @@ fn (cfg DocConfig) write_content(cn &doc.DocNode, dcs &doc.Doc, mut hw strings.B
 }
 
 fn (cfg DocConfig) gen_html(idx int) string {
-	dcs := cfg.docs[idx]
-	mut toc := strings.new_builder(200)
-	mut toc2 := strings.new_builder(200)
+	mut symbols_toc := strings.new_builder(200)
+	mut modules_toc := strings.new_builder(200)
 	mut contents := strings.new_builder(200)
+	dcs := cfg.docs[idx]
+	dcs_contents := dcs.contents.arr()
 	// generate toc first
 	contents.writeln(doc_node_html(dcs.head, '', true, dcs.table))
-	for cn in dcs.contents {
+	for cn in dcs_contents {
 		cfg.write_content(&cn, &dcs, mut contents)
-		if cn.attrs['parent'] == 'Constants' || cn.attrs['category'] == 'Methods' {
-			continue
-		}
-		write_toc(cn, dcs.contents, mut toc)
+		write_toc(cn, dcs_contents, mut symbols_toc)
 	} // write head
 	// write css
 	version := if cfg.manifest.version.len != 0 { cfg.manifest.version } else { '' }
@@ -481,39 +461,37 @@ fn (cfg DocConfig) gen_html(idx int) string {
 			}
 			names := doc.head.name.split('.')
 			submod_prefix = if names.len > 1 { names[0] } else { doc.head.name }
-			href_name := if ('vlib' in cfg.input_path &&
+			href_name := if (dcs.is_vlib &&
 				doc.head.name == 'builtin' && !cfg.include_readme) ||
 				doc.head.name == 'README' {
 				'./index.html'
 			} else if submod_prefix !in cfg.docs.map(it.head.name) {
 				'#'
 			} else {
-				'./' + doc.head.name + '.html'
+				'./${doc.head.name}.html'
 			}
 			submodules := cfg.docs.filter(it.head.name.starts_with(submod_prefix + '.'))
 			dropdown := if submodules.len > 0 { cfg.assets['arrow_icon'] } else { '' }
-			mut is_submodule_open := false
-			for _, cdoc in submodules {
-				if cdoc.head.name == dcs.head.name {
-					is_submodule_open = true
-				}
-			}
 			active_class := if doc.head.name == dcs.head.name { ' active' } else { '' }
-			toc2.write('<li class="open$active_class"><div class="menu-row">$dropdown<a href="$href_name">$submod_prefix</a></div>')
+			modules_toc.write('<li class="open$active_class"><div class="menu-row">$dropdown<a href="$href_name">$submod_prefix</a></div>')
 			for j, cdoc in submodules {
 				if j == 0 {
-					toc2.write('<ul>')
+					modules_toc.write('<ul>')
 				}
 				submod_name := cdoc.head.name.all_after(submod_prefix + '.')
 				sub_selected_classes := if cdoc.head.name == dcs.head.name { ' class="active"' } else { '' }
-				toc2.write('<li$sub_selected_classes><a href="./${cdoc.head.name}.html">$submod_name</a></li>')
+				modules_toc.write('<li$sub_selected_classes><a href="./${cdoc.head.name}.html">$submod_name</a></li>')
 				if j == submodules.len - 1 {
-					toc2.write('</ul>')
+					modules_toc.write('</ul>')
 				}
 			}
-			toc2.write('</li>')
+			modules_toc.write('</li>')
 		}
 	}
+	modules_toc_str := modules_toc.str()
+	symbols_toc_str := symbols_toc.str()
+	modules_toc.free()
+	symbols_toc.free()
 	return html_content.replace('{{ title }}', dcs.head.name).replace('{{ head_name }}',
 		header_name).replace('{{ version }}', version).replace('{{ light_icon }}', cfg.assets['light_icon']).replace('{{ dark_icon }}',
 		cfg.assets['dark_icon']).replace('{{ menu_icon }}', cfg.assets['menu_icon']).replace('{{ head_assets }}',
@@ -524,12 +502,12 @@ fn (cfg DocConfig) gen_html(idx int) string {
 		'\n	<link rel="stylesheet" href="' + cfg.assets['doc_css'] + '" />\n	<link rel="stylesheet" href="' +
 			cfg.assets['normalize_css'] + '" />'
 	}).replace('{{ toc_links }}', if cfg.is_multi || cfg.docs.len > 1 {
-		toc2.str()
+		modules_toc_str
 	} else {
-		toc.str()
+		symbols_toc_str
 	}).replace('{{ contents }}', contents.str()).replace('{{ right_content }}', if cfg.is_multi &&
 		cfg.docs.len > 1 && dcs.head.name != 'README' {
-		'<div class="doc-toc"><ul>' + toc.str() + '</ul></div>'
+		'<div class="doc-toc"><ul>' + symbols_toc_str + '</ul></div>'
 	} else {
 		''
 	}).replace('{{ footer_content }}', cfg.gen_footer_text(idx)).replace('{{ footer_assets }}',
@@ -547,14 +525,13 @@ fn (cfg DocConfig) gen_plaintext(idx int) string {
 	if dcs.head.comment.trim_space().len > 0 && !cfg.pub_only {
 		pw.writeln(dcs.head.comment.split_into_lines().map('    ' + it).join('\n'))
 	}
-	for cn in dcs.contents {
+	for _, cn in dcs.contents {
 		pw.writeln(cn.content)
 		if cn.comment.len > 0 && !cfg.pub_only {
 			pw.writeln(cn.comment.trim_space().split_into_lines().map('    ' + it).join('\n'))
 		}
 		if cfg.show_loc {
-			pw.writeln('Location: $cn.file_path:$cn.pos.line')
-			pw.write('\n')
+			pw.writeln('Location: $cn.file_path:$cn.pos.line\n')
 		}
 	}
 	return pw.str()
@@ -568,7 +545,7 @@ fn (cfg DocConfig) gen_markdown(idx int, with_toc bool) string {
 	if with_toc {
 		hw.writeln('## Contents')
 	}
-	for cn in dcs.contents {
+	for _, cn in dcs.contents {
 		name := cn.name.all_after(dcs.head.name + '.')
 		if with_toc {
 			hw.writeln('- [#$name](${slug(name)})')
@@ -595,7 +572,7 @@ fn (cfg DocConfig) gen_footer_text(idx int) string {
 
 fn (cfg DocConfig) render_doc(doc doc.Doc, i int) (string, string) {
 	// since builtin is generated first, ignore it
-	mut name := if ('vlib' in cfg.input_path &&
+	mut name := if (doc.is_vlib &&
 		doc.head.name == 'builtin' && !cfg.include_readme) ||
 		doc.head.name == 'README' {
 		'index'
@@ -627,7 +604,7 @@ fn (cfg DocConfig) work_processor(mut work sync.Channel, mut wg sync.WaitGroup)
 		}
 		file_name, content := cfg.render_doc(pdoc.d, pdoc.i)
 		output_path := os.join_path(cfg.output_path, file_name)
-		println('Generating ${output_path}...')
+		println('Generating ${output_path}')
 		os.write_file(output_path, content)
 	}
 	wg.done()
@@ -660,16 +637,15 @@ fn (cfg DocConfig) render() map[string]string {
 }
 
 fn (mut cfg DocConfig) render_static() {
-	if cfg.output_type == .html {
-		cfg.assets = {
-			'doc_css': cfg.get_resource(css_js_assets[0], true)
-			'normalize_css': cfg.get_resource(css_js_assets[1], true)
-			'doc_js': cfg.get_resource(css_js_assets[2], !cfg.serve_http)
-			'light_icon': cfg.get_resource('light.svg', true)
-			'dark_icon': cfg.get_resource('dark.svg', true)
-			'menu_icon': cfg.get_resource('menu.svg', true)
-			'arrow_icon': cfg.get_resource('arrow.svg', true)
-		}
+	if cfg.output_type != .html { return }
+	cfg.assets = {
+		'doc_css': cfg.get_resource(css_js_assets[0], true),
+		'normalize_css': cfg.get_resource(css_js_assets[1], true),
+		'doc_js': cfg.get_resource(css_js_assets[2], !cfg.serve_http),
+		'light_icon': cfg.get_resource('light.svg', true),
+		'dark_icon': cfg.get_resource('dark.svg', true),
+		'menu_icon': cfg.get_resource('menu.svg', true),
+		'arrow_icon': cfg.get_resource('arrow.svg', true)
 	}
 }
 
@@ -692,6 +668,20 @@ fn (cfg DocConfig) get_readme(path string) string {
 	return readme_contents
 }
 
+fn (cfg DocConfig) emit_generate_err(err string, errcode int) {
+	mut err_msg := err
+	if errcode == 1 {
+		mod_list := get_modules_list(cfg.input_path, []string{})
+		println('Available modules:\n==================')
+		for mod in mod_list {
+			println(mod.all_after('vlib/').all_after('modules/').replace('/',
+				'.'))
+		}
+		err_msg += ' Use the `-m` flag when generating docs from a directory that has multiple modules.'
+	}
+	eprintln(err_msg)
+}
+
 fn (mut cfg DocConfig) generate_docs_from_file() {
 	if cfg.output_path.len == 0 {
 		if cfg.output_type == .unset {
@@ -739,68 +729,52 @@ fn (mut cfg DocConfig) generate_docs_from_file() {
 		}
 	}
 	dirs := if cfg.is_multi { get_modules_list(cfg.input_path, []string{}) } else { [cfg.input_path] }
+	is_local_and_single := cfg.is_local && !cfg.is_multi
 	for dirpath in dirs {
-		cfg.vprintln('Generating docs for ${dirpath}...')
-		if cfg.is_local && !cfg.is_multi {
-			dcs := doc.generate_from_pos(dirpath, cfg.local_filename, cfg.local_pos) or {
-				mut err_msg := err
-				if errcode == 1 {
-					mod_list := get_modules_list(cfg.input_path, []string{})
-					println('Available modules:\n==================')
-					for mod in mod_list {
-						println(mod.all_after('vlib/').all_after('modules/').replace('/',
-							'.'))
-					}
-					err_msg += ' Use the `-m` flag when generating docs from a directory that has multiple modules.'
-				}
-				eprintln(err_msg)
+		mut dcs := doc.Doc{}
+		cfg.vprintln('Generating docs for ${dirpath}')
+		if is_local_and_single {
+			dcs = doc.generate_from_pos(dirpath, cfg.local_filename, cfg.local_pos) or {
+				cfg.emit_generate_err(err, errcode)
 				exit(1)
 			}
-			if dcs.contents.len == 0 {
-				continue
-			}
-			cfg.docs << dcs
 		} else {
-			mut dcs := doc.generate(dirpath, cfg.pub_only, true) or {
-				mut err_msg := err
-				if errcode == 1 {
-					mod_list := get_modules_list(cfg.input_path, []string{})
-					println('Available modules:\n==================')
-					for mod in mod_list {
-						println(mod.all_after('vlib/').all_after('modules/').replace('/',
-							'.'))
-					}
-					err_msg += ' Use the `-m` flag when generating docs from a directory that has multiple modules.'
-				}
-				eprintln(err_msg)
+			dcs = doc.generate(dirpath, cfg.pub_only, true) or {
+				cfg.emit_generate_err(err, errcode)
 				exit(1)
 			}
-			if dcs.contents.len == 0 {
-				continue
-			}
+		}
+		if dcs.contents.len == 0 {
+			continue
+		}
+		if !is_local_and_single {
 			if cfg.is_multi || (!cfg.is_multi && cfg.include_readme) {
 				readme_contents := cfg.get_readme(dirpath)
 				dcs.head.comment = readme_contents
 			}
+			mut new_contents := map[string]doc.DocNode
 			if cfg.pub_only {
-				for i, c in dcs.contents {
-					dcs.contents[i].content = c.content.all_after('pub ')
+				for name, oc in dcs.contents {
+					mut c := oc
+					c.content = c.content.all_after('pub ')
+					for i, cc in c.children {
+						c.children[i].content = cc.content.all_after('pub ')
+					}
+					new_contents[name] = c
 				}
 			}
 			if !cfg.is_multi && cfg.symbol_name.len > 0 {
-				mut new_contents := []doc.DocNode{}
-				for cn in dcs.contents {
-					if cn.name != cfg.symbol_name {
-						continue
+				if cfg.symbol_name in dcs.contents {
+					new_contents[cfg.symbol_name] = dcs.contents[cfg.symbol_name]
+					children := dcs.contents[cfg.symbol_name].children
+					for _, c in children {
+						new_contents[c.name] = c
 					}
-					new_contents << cn
-					break
 				}
-				new_contents << dcs.contents.find_children_of(cfg.symbol_name)
-				dcs.contents = new_contents
 			}
-			cfg.docs << dcs
+			dcs.contents = new_contents
 		}
+		cfg.docs << dcs
 	}
 	if 'vlib' in cfg.input_path {
 		mut docs := cfg.docs.filter(it.head.name == 'builtin')
@@ -890,22 +864,6 @@ fn get_ignore_paths(path string) ?[]string {
 	return res.map(it.replace('/', os.path_separator))
 }
 
-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(vexe_path, '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.is_dir_empty(path) {
-			continue
-		}
-		return path
-	}
-	return error('vdoc: Module "$mod" not found.')
-}
-
 fn is_included(path string, ignore_paths []string) bool {
 	if path.len == 0 {
 		return true
@@ -946,7 +904,7 @@ fn get_modules_list(path string, ignore_paths2 []string) []string {
 fn (cfg DocConfig) get_resource(name string, minify bool) string {
 	path := os.join_path(res_path, name)
 	mut res := os.read_file(path) or {
-		panic('could not read $path')
+		panic('vdoc: could not read $path')
 	}
 	if minify {
 		if name.ends_with('.js') {
@@ -961,7 +919,7 @@ fn (cfg DocConfig) get_resource(name string, minify bool) string {
 	} else {
 		output_path := os.join_path(cfg.output_path, name)
 		if !os.exists(output_path) {
-			println('Generating ${output_path}...')
+			println('Generating ${output_path}')
 			os.write_file(output_path, res)
 		}
 		return name
@@ -1071,6 +1029,9 @@ fn main() {
 		eprintln('vdoc: No input path found.')
 		exit(1)
 	}
+	if cfg.output_path == 'stdout' && cfg.output_type == .html {
+		cfg.inline_assets = true
+	}
 	$if windows {
 		cfg.input_path = cfg.input_path.replace('/', os.path_separator)
 	} $else {
@@ -1083,8 +1044,8 @@ fn main() {
 		cfg.input_path = os.join_path(vexe_path, 'vlib')
 	} else if !is_path {
 		cfg.vprintln('Input "$cfg.input_path" is not a valid path. Looking for modules named "$cfg.input_path"...')
-		mod_path := lookup_module(cfg.input_path) or {
-			eprintln(err)
+		mod_path := doc.lookup_module(cfg.input_path) or {
+			eprintln('vdoc: $err')
 			exit(1)
 		}
 		cfg.input_path = mod_path
diff --git a/vlib/v/doc/doc.v b/vlib/v/doc/doc.v
index d5c1640f8f..dd87379d8e 100644
--- a/vlib/v/doc/doc.v
+++ b/vlib/v/doc/doc.v
@@ -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)
+}
diff --git a/vlib/v/doc/doc_test.v b/vlib/v/doc/doc_test.v
index 8036b0cae9..6ea3c2eae1 100644
--- a/vlib/v/doc/doc_test.v
+++ b/vlib/v/doc/doc_test.v
@@ -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
+}