scanner: adjust comments to make golint happy

Signed-off-by: Alejandro Mery <amery@geeks.cl>

scanner/scanner.go

@@ -5,14 +5,17 @@ import (
 )
 
 const (
+	// EOF is a dummy rune representing End-Of-File
 	EOF = -1
 )
 
+// A Position in the input string and in the line-based document
 type Position struct {
 	Offset       uint
 	Line, Column uint
 }
 
+// An Scanner represent the low level layer for text parsers
 type Scanner struct {
 	name  string
 	input string
@@ -34,24 +37,24 @@ func NewScannerFromString(name, input string) *Scanner {
 	}
 }
 
-// Current length of the upcomming Terminal
+// Length returns the number of bytes and runes in the Terminal that is been detected
 func (l *Scanner) Length() (uint, uint) {
 	return l.cursor.Offset - l.base.Offset, l.runes
 }
 
-// Is the upcoming Terminal stil empty?
+// Empty tells if there are no runes accounted for the next Terminal yet
 func (l *Scanner) Empty() bool {
 	return l.runes == 0
 }
 
-// Move cursor forward
+// StepForth moves the cursor forward
 func (l *Scanner) StepForth(runes, bytes uint) {
 	l.cursor.Offset += bytes
 	l.cursor.Column += runes
 	l.runes += runes
 }
 
-// Move cursor backward
+// StepBack moves the cursor backward
 func (l *Scanner) StepBack(runes, bytes uint) {
 	l.cursor.Offset -= bytes
 	// FIXME: what if column goes < 1?
@@ -59,13 +62,13 @@ func (l *Scanner) StepBack(runes, bytes uint) {
 	l.runes -= runes
 }
 
-// Moves the cursor back to the back
+// Reset moves the cursor back to the base
 func (l *Scanner) Reset() {
 	l.cursor = l.base
 	l.runes = 0
 }
 
-// Trashes everything up to the cursor
+// Skip trashes everything up to the cursor
 func (l *Scanner) Skip() {
 	l.base = l.cursor
 	l.runes = 0
@@ -77,7 +80,7 @@ func (l *Scanner) NewLine() {
 	l.cursor.Column = 1
 }
 
-// Return the next rune but not moving the cursor
+// Peek returns the next rune but not moving the cursor
 func (l *Scanner) Peek() (rune, uint) {
 	if l.cursor.Offset == uint(len(l.input)) {
 		return EOF, 0
@@ -86,7 +89,7 @@ func (l *Scanner) Peek() (rune, uint) {
 	return r, uint(bytes)
 }
 
-// Return the next rune but moving the cursor
+// Next returns the next rune but moving the cursor
 func (l *Scanner) Next() (rune, uint) {
 	r, bytes := l.Peek()
 	if bytes > 0 {

scanner/terminal.go

@@ -4,14 +4,14 @@ import (
 	"unicode/utf8"
 )
 
-// A literal element within a document
+// A Terminal represents literal element within a document
 type Terminal struct {
 	val          string
 	bytes, runes uint
 	line, col    uint
 }
 
-// Creates a new Terminal
+// NewTerminalFull returns a new Terminal instance
 func NewTerminalFull(val string, bytes, runes, line, col uint) *Terminal {
 	return &Terminal{
 		val:   val,
@@ -22,7 +22,7 @@ func NewTerminalFull(val string, bytes, runes, line, col uint) *Terminal {
 	}
 }
 
-// Creates a new Terminal without knowing it's length
+// NewTerminal creates a Terminal instance without knowing it's length
 func NewTerminal(val string, line, col uint) *Terminal {
 	bytes := uint(len(val))
 	runes := uint(utf8.RuneCountInString(val))
@@ -30,12 +30,14 @@ func NewTerminal(val string, line, col uint) *Terminal {
 	return NewTerminalFull(val, bytes, runes, line, col)
 }
 
-// Position of the terminal in the document
+// Position retuns the position (line and column)
+// of the Terminal in the source document
 func (t *Terminal) Position() (uint, uint) {
 	return t.line, t.col
 }
 
-// Value and size of the Terminal
+// Value returns the string corresponding to
+// this Terminal and it's size in bytes and runes
 func (t *Terminal) Value() (string, uint, uint) {
 	return t.val, t.bytes, t.runes
 }