tools: support a `v vet -p file.v` option that will warn about private functions with missing documentation

cmd/tools/vvet/vvet.v

@@ -25,6 +25,7 @@ struct Options {
 	is_verbose          bool
 	show_warnings       bool
 	use_color           bool
+	doc_private_fns_too bool
 }
 
 const term_colors = term.can_show_color_on_stderr()
@@ -38,6 +39,7 @@ fn main() {
 			is_verbose: '-verbose' in vet_options || '-v' in vet_options
 			show_warnings: '-hide-warnings' !in vet_options && '-w' !in vet_options
 			use_color: '-color' in vet_options || (term_colors && '-nocolor' !in vet_options)
+			doc_private_fns_too: '-p' in vet_options
 		}
 	}
 	mut paths := cmdline.only_non_options(vet_options)
@@ -110,11 +112,26 @@ fn (mut vt Vet) vet_file(path string) {
 
 // vet_line vets the contents of `line` from `vet.file`.
 fn (mut vt Vet) vet_line(lines []string, line string, lnumber int) {
-	// Vet public functions
+	vt.vet_fn_documentation(lines, line, lnumber)
-	if line.starts_with('pub fn') || (line.starts_with('fn ') && !(line.starts_with('fn C.')
+}
-		|| line.starts_with('fn main'))) {
+
+// vet_fn_documentation ensures that functions are documented
+fn (mut vt Vet) vet_fn_documentation(lines []string, line string, lnumber int) {
+	if line.starts_with('fn C.') {
+		return
+	}
+	is_pub_fn := line.starts_with('pub fn ')
+	is_fn := is_pub_fn || line.starts_with('fn ')
+	if !is_fn {
+		return
+	}
+	if line.starts_with('fn main') {
+		return
+	}
+	if !(is_pub_fn || vt.opt.doc_private_fns_too) {
+		return
+	}
 	// Scan function declarations for missing documentation
-		is_pub_fn := line.starts_with('pub fn')
 	if lnumber > 0 {
 		collect_tags := fn (line string) []string {
 			mut cleaned := line.all_before('/')
@@ -158,11 +175,9 @@ fn (mut vt Vet) vet_line(lines []string, line string, lnumber int) {
 			}
 			if grab {
 				clean_line := line.all_before_last('{').trim(' ')
-					if is_pub_fn {
 				vt.warn('Function documentation seems to be missing for "$clean_line".',
 					lnumber, .doc)
 			}
-				}
 		} else {
 			fn_name := ident_fn_name(line)
 			mut grab := true
@@ -175,11 +190,9 @@ fn (mut vt Vet) vet_line(lines []string, line string, lnumber int) {
 					break
 				} else if prev_line.starts_with('// $fn_name') {
 					grab = false
-						if is_pub_fn {
 					clean_line := line.all_before_last('{').trim(' ')
-							vt.warn('The documentation for "$clean_line" seems incomplete.',
+					vt.warn('The documentation for "$clean_line" seems incomplete.', lnumber,
-								lnumber, .doc)
+						.doc)
-						}
 					break
 				} else if prev_line.starts_with('[') {
 					tags << collect_tags(prev_line)
@@ -190,14 +203,11 @@ fn (mut vt Vet) vet_line(lines []string, line string, lnumber int) {
 			}
 			if grab {
 				clean_line := line.all_before_last('{').trim(' ')
-					if is_pub_fn {
 				vt.warn('A function name is missing from the documentation of "$clean_line".',
 					lnumber, .doc)
 			}
 		}
 	}
-		}
-	}
 }
 
 fn (vt &Vet) vprintln(s string) {

cmd/v/help/vet.txt

@@ -14,5 +14,8 @@ Options:
   -v, -verbose
      Enable verbose logging.
 
+  -p
+     Report private functions with missing documentation too (by default, only the `pub fn` functions will be reported).
+
   -force
      (NB: vet development only!) Do not skip the vet regression tests.