added documentation

barely.go

@@ -2,6 +2,7 @@
 // Use of this source code is governed by the MIT-styled
 // license that can be found in the LICENSE file.
 
+// barely is a notmuch-frontend inspired by alot.
 package main
 
 import (
@@ -18,8 +19,14 @@ import (
 )
 
 const (
-	Version       = "0.1"
-	UserAgent     = "barely/" + Version
+	// Version is the version number of barely.
+	Version = "0.1"
+
+	// UserAgent is the User Agent string attached to mail messages.
+	UserAgent = "barely/" + Version
+
+	// StderrLogFile is a file in the temporary files directory
+	// where Xapians messy stderr output gets redirected to.
 	StderrLogFile = "barely.log"
 )
 

buffer.go

@@ -39,6 +39,7 @@ func invalidCommand(cmd string) {
 	StatusLine = "invalid command: " + cmd
 }
 
+// Init initializes the BufferStack and executes the initial command set in Config.
 func (b *BufferStack) Init() {
 	fields := strings.Fields(config.General.Initial_Command)
 	if len(fields) > 0 {
@@ -52,6 +53,7 @@ func (b *BufferStack) Init() {
 	}
 }
 
+// Push pushes a new buffer on the stack. Focus is changed to that buffer.
 func (b *BufferStack) Push(n Buffer) {
 	for i, buf := range b.buffers {
 		// If the buffer already exists, change to it instead.
@@ -67,9 +69,10 @@ func (b *BufferStack) Push(n Buffer) {
 	b.refresh()
 }
 
-// This string will be displayed at the bottom of the screen. useful for error messages.
+// StatusLine is displayed at the bottom of the screen. useful for error messages.
 var StatusLine string
 
+// Pop pops the last buffer from the stack.
 func (b *BufferStack) Pop() {
 	if len(b.buffers) == 0 {
 		return
@@ -79,6 +82,7 @@ func (b *BufferStack) Pop() {
 	b.refresh()
 }
 
+// refresh clears the terminal and redraws everything.
 func (b *BufferStack) refresh() {
 	termbox.Clear(0, 0)
 	if len(b.buffers) == 0 {
@@ -103,6 +107,7 @@ func (b *BufferStack) refresh() {
 	termbox.Flush()
 }
 
+// handleCommand executes global commands.
 func (b *BufferStack) handleCommand(cmd string, args []string) bool {
 	switch cmd {
 	case "close":
@@ -132,6 +137,7 @@ func (b *BufferStack) handleCommand(cmd string, args []string) bool {
 	return true
 }
 
+// HandleEvent handles termbox events and invokes commands if their keybinding was pressed.
 func (b *BufferStack) HandleEvent(event *termbox.Event) {
 	if len(b.buffers) == 0 {
 		return

composebuffer.go

@@ -17,26 +17,32 @@ import (
 	"github.com/nsf/termbox-go"
 )
 
+// ComposeBuffer is a MailBuffer that allows editing and sending the viewed message.
 type ComposeBuffer struct {
 	mb *MailBuffer
 }
 
+// NewComposeBuffer creates a new Composebuffer for displaying a mail.
 func NewComposeBuffer(m *Mail) *ComposeBuffer {
 	return &ComposeBuffer{NewMailBufferFromMail(m)}
 }
 
+// Draw draws the buffer content.
 func (b *ComposeBuffer) Draw() {
 	b.mb.Draw()
 }
 
+// Title returns the buffer's title string.
 func (b *ComposeBuffer) Title() string {
 	return b.mb.mail.Header.Get("Message-ID")
 }
 
+// Name returns the buffer's name.
 func (b *ComposeBuffer) Name() string {
 	return "compose"
 }
 
+// Close closes the buffer.
 func (b *ComposeBuffer) Close() {
 	b.mb.Close()
 }
@@ -143,6 +149,7 @@ func (b *ComposeBuffer) openEditor(stack *BufferStack) {
 	stack.refresh()
 }
 
+// HandleCommand executes buffer local commands.
 func (b *ComposeBuffer) HandleCommand(cmd string, args []string, stack *BufferStack) bool {
 	switch cmd {
 	case "reply", "raw": // disallow invalid commands in compose mode

config.go

@@ -25,6 +25,7 @@ var specialKeys = map[string]termbox.Key{
 	"enter":    termbox.KeyEnter,
 }
 
+// KeyBinding represents a single keybinding.
 type KeyBinding struct {
 	Ch      rune
 	Key     termbox.Key // for nonprintables
@@ -34,6 +35,7 @@ type KeyBinding struct {
 	Args    []string
 }
 
+// UnmarshalText implements the encoding.TextUnmarshaller interface.
 func (k *KeyBinding) UnmarshalText(text []byte) error {
 	str := string(text)
 	fields := strings.Fields(str)
@@ -57,10 +59,12 @@ func (k *KeyBinding) UnmarshalText(text []byte) error {
 	return nil
 }
 
+// KeyBindings represent a set of keybindings.
 type KeyBindings struct {
 	Key []*KeyBinding
 }
 
+// Account represents a mail account set up to send mail.
 type Account struct {
 	Addr             string
 	Sendmail_Command string
@@ -69,11 +73,13 @@ type Account struct {
 	Draft_Dir        string
 }
 
+// TagAlias represents an alias for tags.
 type TagAlias struct {
 	tag   string
 	alias string
 }
 
+// UnmarshalText implements the encoding.TextUnmarshaller interface.
 func (t *TagAlias) UnmarshalText(text []byte) error {
 	str := string(text)
 	fields := strings.Fields(str)
@@ -248,6 +254,8 @@ func preparePostConfig(pcfg *PostConfig, cfg *Config) {
 	}
 }
 
+// LoadConfig loads the configuration from the standard configuration file path and sets the
+// global config struct.
 func LoadConfig() {
 	err := gcfg.ReadStringInto(&config, DefaultCfg)
 	if err != nil {
@@ -262,6 +270,10 @@ func LoadConfig() {
 	preparePostConfig(&pconfig, &config)
 }
 
+// getBinding returns a key binding fitting a pressed key (Ch, Key) for a specific section.
+// If no such binding exists, it returns nil.
+//
+// Global bindings are associated to the section "".
 func getBinding(section string, Ch rune, Key termbox.Key) *KeyBinding {
 	sec := config.Bindings[section]
 	if sec == nil {
@@ -277,6 +289,7 @@ func getBinding(section string, Ch rune, Key termbox.Key) *KeyBinding {
 	return nil
 }
 
+// getAccount fetches an account for a given mail address.
 func getAccount(addr string) *Account {
 	for _, val := range config.Account {
 		if val.Addr == addr {

helpbuffer.go

@@ -10,6 +10,7 @@ import (
 	"github.com/nsf/termbox-go"
 )
 
+// HelpBuffer displays a cheat sheet of all usable keybindings in the current context.
 type HelpBuffer struct {
 	bufferName string
 }
@@ -28,6 +29,7 @@ func drawHelpSection(y int, name string) int {
 	return y
 }
 
+// Draw draws the content of the buffer.
 func (b *HelpBuffer) Draw() {
 	printLine(0, 0, "Command Help", int(termbox.AttrBold), 0)
 	y := 2
@@ -40,17 +42,21 @@ func (b *HelpBuffer) Draw() {
 	y = drawHelpSection(y, b.bufferName)
 }
 
+// Title returns the title string of the buffer.
 func (b *HelpBuffer) Title() string {
 	return "on buffer \"" + b.bufferName + "\""
 }
 
+// Name returns the name of the buffer.
 func (b *HelpBuffer) Name() string {
 	return "help"
 }
 
+// Close closes the buffer.
 func (b *HelpBuffer) Close() {
 }
 
+// HandleCommand handles buffer local commands.
 func (b *HelpBuffer) HandleCommand(cmd string, args []string, stack *BufferStack) bool {
 	return false
 }

mail.go

@@ -31,11 +31,14 @@ import (
 	qp "gopkg.in/alexcesaro/quotedprintable.v2"
 )
 
+// Part represents a multipart part. Messages that do not have multipart content
+// are still represented as multipart messages with one part internally.
 type Part struct {
 	Header textproto.MIMEHeader
 	Body   string
 }
 
+// Mail represents the content of one mail message.
 type Mail struct {
 	Header mail.Header
 	Parts  []Part
@@ -263,7 +266,7 @@ func (m *Mail) attachFile(filename string) error {
 	return nil
 }
 
-// encodeMail encodes a Mail structure to 7bit text.
+// Encode encodes a Mail structure to 7bit text.
 func (m *Mail) Encode() (string, error) {
 	if len(m.Parts) == 0 {
 		return "", errors.New("Error: message without content")

mailbuffer.go

@@ -30,6 +30,7 @@ type MailBuffer struct {
 	lastSearch string
 }
 
+// NewMailBuffer creates a MailBuffer from a mail file called filename.
 func NewMailBuffer(filename string) *MailBuffer {
 	m, err := readMail(filename)
 	if err != nil {
@@ -43,6 +44,7 @@ func NewMailBuffer(filename string) *MailBuffer {
 	return buf
 }
 
+// NewMailBufferFromMail creates a MailBuffer from a Mail structure.
 func NewMailBufferFromMail(m *Mail) *MailBuffer {
 	buf := new(MailBuffer)
 	var err error
@@ -160,6 +162,7 @@ func (b *MailBuffer) drawHeader() {
 	drawField(3, "Subject", getHeader("Subject"))
 }
 
+// Draw draws the content of the buffer.
 func (b *MailBuffer) Draw() {
 	w, h := termbox.Size()
 	cbuf := termbox.CellBuffer()
@@ -191,18 +194,22 @@ func (b *MailBuffer) Draw() {
 
 }
 
+// Title returns the title string of the buffer.
 func (b *MailBuffer) Title() string {
 	return "reading " + b.mail.Header.Get("Message-ID")
 }
 
+// Name returns the name string of the buffer.
 func (b *MailBuffer) Name() string {
 	return "mail"
 }
 
+// Close closes the buffer.
 func (b *MailBuffer) Close() {
 	os.RemoveAll(b.tmpDir)
 }
 
+// attachmentName returns the filename of a part if present in its headers or "" if not.
 func attachmentName(p *Part) string {
 	_, params, err := mime.ParseMediaType(p.Header.Get("Content-Type"))
 	if err != nil {
@@ -218,6 +225,10 @@ func attachmentName(p *Part) string {
 	return params["filename"]
 }
 
+// openAttachment decodes a part to a temporary file and opens the configured program
+// for handling that file.
+//
+// The program runs in the background and openAttachment returns immediately.
 func openAttachment(p *Part, dir string) {
 	name := attachmentName(p)
 	if name == "" {
@@ -300,6 +311,7 @@ func (b *MailBuffer) searchCmd(term string, reverse bool) int {
 	return (idx - hits) / w
 }
 
+// HandleCommand handles buffer local commands.
 func (b *MailBuffer) HandleCommand(cmd string, args []string, stack *BufferStack) bool {
 	switch cmd {
 	case "move":

maildir/maildir.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by the MIT-styled
 // license that can be found in the LICENSE file.
 
-// Maildir provides simple routines to add messages to a Maildir.
+// Package maildir provides simple routines to add messages to a Maildir.
 package maildir
 
 import (

prompt.go

@@ -10,15 +10,18 @@ import (
 	termbox "github.com/nsf/termbox-go"
 )
 
+// Prompt represents the command prompt at the bottom of the screen.
 type Prompt struct {
 	text   []rune
 	cursor int
 }
 
+// Active returns true if the prompt is on and false if it is off.
 func (p *Prompt) Active() bool {
 	return p.text != nil
 }
 
+// Draw draws the prompt.
 func (p *Prompt) Draw() {
 	w, h := termbox.Size()
 	printLine(0, h-1, ":"+string(p.text)+" ", -1, -1)
@@ -49,6 +52,8 @@ func (p *Prompt) delChar() {
 	}
 }
 
+// HandleEvent handles termbox events. If the prompt is active, key bindings do not work
+// and this function gets all the key events.
 func (p *Prompt) HandleEvent(e *termbox.Event) (string, []string) {
 	if e.Ch == 0 {
 		switch e.Key {
@@ -90,6 +95,7 @@ func (p *Prompt) HandleEvent(e *termbox.Event) (string, []string) {
 	return "", nil
 }
 
+// Activate switches on the prompt with an initial string.
 func (p *Prompt) Activate(startstr string) {
 	p.text = append(p.text, []rune(startstr+" ")...)
 	if startstr == "" {