ui: document Message / Printer / Terminal interfaces

internal/ui/message.go

@@ -19,33 +19,35 @@ func NewMessage(term Terminal, verbosity uint) *Message {
 	}
 }
 
-// E reports an error
+// E reports an error. This message is always printed to stderr.
 func (m *Message) E(msg string, args ...interface{}) {
 	m.term.Error(fmt.Sprintf(msg, args...))
 }
 
 // S prints a message, this is should only be used for very important messages
-// that are not errors.
+// that are not errors. The message is even printed if --quiet is specified.
 func (m *Message) S(msg string, args ...interface{}) {
 	m.term.Print(fmt.Sprintf(msg, args...))
 }
 
-// P prints a message if verbosity >= 1, this is used for normal messages which
+// P prints a message if verbosity >= 1 (neither --quiet nor --verbose is specified),
-// are not errors.
+// this is used for normal messages which are not errors.
 func (m *Message) P(msg string, args ...interface{}) {
 	if m.v >= 1 {
 		m.term.Print(fmt.Sprintf(msg, args...))
 	}
 }
 
-// V prints a message if verbosity >= 2, this is used for verbose messages.
+// V prints a message if verbosity >= 2 (equivalent to --verbose), this is used for
+// verbose messages.
 func (m *Message) V(msg string, args ...interface{}) {
 	if m.v >= 2 {
 		m.term.Print(fmt.Sprintf(msg, args...))
 	}
 }
 
-// VV prints a message if verbosity >= 3, this is used for debug messages.
+// VV prints a message if verbosity >= 3 (equivalent to --verbose=2), this is used for
+// debug messages.
 func (m *Message) VV(msg string, args ...interface{}) {
 	if m.v >= 3 {
 		m.term.Print(fmt.Sprintf(msg, args...))

internal/ui/progress/printer.go

@@ -6,18 +6,27 @@ import "testing"
 // at different log levels.
 // It must be safe to call its methods from concurrent goroutines.
 type Printer interface {
+	// NewCounter returns a new progress counter. It is not shown if --quiet or --json is specified.
 	NewCounter(description string) *Counter
+	// NewCounterTerminalOnly returns a new progress counter that is only shown if stdout points to a
+	// terminal. It is not shown if --quiet or --json is specified.
 	NewCounterTerminalOnly(description string) *Counter
 
-	// E prints to stderr
+	// E reports an error. This message is always printed to stderr.
+	// Appends a newline if not present.
 	E(msg string, args ...interface{})
-	// S prints to stdout
+	// S prints a message, this is should only be used for very important messages
+	// that are not errors. The message is even printed if --quiet is specified.
+	// Appends a newline if not present.
 	S(msg string, args ...interface{})
-	// P prints to stdout unless quiet was passed
+	// P prints a message if verbosity >= 1 (neither --quiet nor --verbose is specified),
+	// this is used for normal messages which are not errors. Appends a newline if not present.
 	P(msg string, args ...interface{})
-	// V prints to stdout if verbose is set once
+	// V prints a message if verbosity >= 2 (equivalent to --verbose), this is used for
+	// verbose messages. Appends a newline if not present.
 	V(msg string, args ...interface{})
-	// VV prints to stdout if verbose is set twice
+	// VV prints a message if verbosity >= 3 (equivalent to --verbose=2), this is used for
+	// debug messages. Appends a newline if not present.
 	VV(msg string, args ...interface{})
 }
 

internal/ui/terminal.go

@@ -5,9 +5,16 @@ import "io"
 // Terminal is used to write messages and display status lines which can be
 // updated. See termstatus.Terminal for a concrete implementation.
 type Terminal interface {
+	// Print writes a line to the terminal. Appends a newline if not present.
 	Print(line string)
+	// Error writes an error to the terminal. Appends a newline if not present.
 	Error(line string)
+	// SetStatus sets the status lines to the terminal.
 	SetStatus(lines []string)
+	// CanUpdateStatus returns true if the terminal can update the status lines.
 	CanUpdateStatus() bool
+	// OutputRaw returns the output writer. Should only be used if there is no
+	// other option. Must not be used in combination with Print, Error, SetStatus
+	// or any other method that writes to the terminal.
 	OutputRaw() io.Writer
 }