log: document all functions, add missing copyright header (#7391)

vlib/log/log.v

@@ -1,9 +1,13 @@
+// Copyright (c) 2019-2020 Alexander Medvednikov. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
 module log
 
 import os
 import time
 import term
 
+// Level defines possible log levels used by `Log`
 pub enum Level {
 	fatal = 1
 	error
@@ -12,6 +16,7 @@ pub enum Level {
 	debug
 }
 
+// tag returns the tag for log level `l` as a string.
 fn tag(l Level) string {
 	return match l {
 		.fatal { term.red('FATAL') }
@@ -30,34 +35,40 @@ interface Logger {
 	debug(s string)
 }
 
+// Log represents a logging object
 pub struct Log {
 mut:
 	level            Level
 	output_label     string
 	ofile            os.File
-	output_to_file   bool
+	output_to_file   bool // if true output to file else use stdout/stderr.
 pub mut:
-	output_file_name string
+	output_file_name string // log output to this file
 }
 
+// set_level sets the internal logging to `level`.
 pub fn (mut l Log) set_level(level Level) {
 	l.level = level
 }
 
+// set_output_level sets the internal logging output to `level`.
 pub fn (mut l Log) set_output_level(level Level) {
 	l.level = level
 }
 
+// set_full_logpath sets the output label and output path from `full_log_path`.
 pub fn (mut l Log) set_full_logpath(full_log_path string) {
 	rlog_file := os.real_path(full_log_path)
 	l.set_output_label(os.file_name(rlog_file))
 	l.set_output_path(os.dir(rlog_file))
 }
 
+// set_output_label sets the `label` for the output.
 pub fn (mut l Log) set_output_label(label string) {
 	l.output_label = label
 }
 
+// set_output_path sets the file to which output is logged to.
 pub fn (mut l Log) set_output_path(output_file_path string) {
 	if l.ofile.is_opened {
 		l.ofile.close()
@@ -70,27 +81,32 @@ pub fn (mut l Log) set_output_path(output_file_path string) {
 	l.ofile = ofile
 }
 
-// Writes the log file content to disk
+// flush writes the log file content to disk.
 pub fn (mut l Log) flush() {
 	l.ofile.flush()
 }
 
+// close closes the log file.
 pub fn (mut l Log) close() {
 	l.ofile.close()
 }
 
+// log_file writes log line `s` with `level` to the log file.
 fn (mut l Log) log_file(s string, level Level) {
 	timestamp := time.now().format_ss()
 	e := tag(level)
 	l.ofile.writeln('$timestamp [$e] $s')
 }
 
+// log_cli writes log line `s` with `level` to stdout.
 fn (l &Log) log_cli(s string, level Level) {
 	f := tag(level)
 	t := time.now()
 	println('[$f $t.format_ss()] $s')
 }
 
+// send_output writes log line `s` with `level` to either the log file or stdout
+// according to the value of the `.output_to_file` field.
 fn (mut l Log) send_output(s &string, level Level) {
 	if l.output_to_file {
 		l.log_file(s, level)
@@ -99,6 +115,7 @@ fn (mut l Log) send_output(s &string, level Level) {
 	}
 }
 
+// fatal logs line `s` via `send_output` if `Log.level` is greater than or equal to the `Level.fatal` category.
 pub fn (mut l Log) fatal(s string) {
 	if l.level < .fatal {
 		return
@@ -108,6 +125,7 @@ pub fn (mut l Log) fatal(s string) {
 	panic('$l.output_label: $s')
 }
 
+// error logs line `s` via `send_output` if `Log.level` is greater than or equal to the `Level.error` category.
 pub fn (mut l Log) error(s string) {
 	if l.level < .error {
 		return
@@ -115,6 +133,7 @@ pub fn (mut l Log) error(s string) {
 	l.send_output(s, .error)
 }
 
+// warn logs line `s` via `send_output` if `Log.level` is greater than or equal to the `Level.warn` category.
 pub fn (mut l Log) warn(s string) {
 	if l.level < .warn {
 		return
@@ -122,6 +141,7 @@ pub fn (mut l Log) warn(s string) {
 	l.send_output(s, .warn)
 }
 
+// info logs line `s` via `send_output` if `Log.level` is greater than or equal to the `Level.info` category.
 pub fn (mut l Log) info(s string) {
 	if l.level < .info {
 		return
@@ -129,6 +149,7 @@ pub fn (mut l Log) info(s string) {
 	l.send_output(s, .info)
 }
 
+// debug logs line `s` via `send_output` if `Log.level` is greater than or equal to the `Level.debug` category.
 pub fn (mut l Log) debug(s string) {
 	if l.level < .debug {
 		return