Documentation.

README.md

@@ -12,14 +12,14 @@ For now, these are the only implemented dialogs:
 * message (error, info, question, warning)
 * file selection
 
-Behavior on Windows, macOS and other UNIXes might differ sliglty.
+Behavior on Windows, macOS and other UNIXes might differ slightly.
 Some of that is intended (reflecting platform differences),
 other bits are unfortunate limitations,
-others still open to be fixed.
+others still are open to be fixed.
 
 ## Why?
 
-There are a bunch of other dialog packages for Go.
+There are a bunch of other dialog packages for Go.\
 Why reinvent this particular wheel?
 
 #### Requirements:

cmd/zenity/main.go

@@ -90,7 +90,7 @@ func setupFlags() {
 	// Message options
 
 	flag.StringVar(&text, "text", "", "Set the dialog text")
-	flag.StringVar(&iconName, "icon-name", "", "Set the dialog icon (error, information, question, warning)")
+	flag.StringVar(&iconName, "icon-name", "", "Set the dialog icon (error, info, question, warning)")
 	flag.StringVar(&okLabel, "ok-label", "", "Set the label of the OK button")
 	flag.StringVar(&cancelLabel, "cancel-label", "", "Set the label of the Cancel button")
 	flag.StringVar(&extraButton, "extra-button", "", "Add an extra button")

file_test.go

@@ -1,67 +1,54 @@
-package zenity
+package zenity_test
 
-import "testing"
+import "github.com/ncruces/zenity"
 
 const defaultPath = ""
+const defaultName = ""
 
-func TestSelectFile(t *testing.T) {
+func ExampleSelectFile() {
-	res, err := SelectFile(Filename(defaultPath), FileFilters{
+	zenity.SelectFile(
-		{"Go files", []string{"*.go"}},
+		zenity.Filename(defaultPath),
-		{"Web files", []string{"*.html", "*.js", "*.css"}},
+		zenity.FileFilters{
-		{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
+			{"Go files", []string{"*.go"}},
-	}.New())
+			{"Web files", []string{"*.html", "*.js", "*.css"}},
-
+			{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
-	if err != nil {
+		}.New())
-		t.Error(err)
+	// Output:
-	} else {
-		t.Logf("%#v", res)
-	}
 }
 
-func TestSelectFileMutiple(t *testing.T) {
+func ExampleSelectFileMutiple() {
-	res, err := SelectFileMutiple(Filename(defaultPath), FileFilters{
+	zenity.SelectFileMutiple(
-		{"Go files", []string{"*.go"}},
+		zenity.Filename(defaultPath),
-		{"Web files", []string{"*.html", "*.js", "*.css"}},
+		zenity.FileFilters{
-		{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
+			{"Go files", []string{"*.go"}},
-	}.New())
+			{"Web files", []string{"*.html", "*.js", "*.css"}},
-
+			{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
-	if err != nil {
+		}.New())
-		t.Error(err)
+	// Output:
-	} else {
-		t.Logf("%#v", res)
-	}
 }
 
-func TestSelectFileSave(t *testing.T) {
+func ExampleSelectFileSave() {
-	res, err := SelectFileSave(Filename(defaultPath), ConfirmOverwrite, FileFilters{
+	zenity.SelectFileSave(
-		{"Go files", []string{"*.go"}},
+		zenity.ConfirmOverwrite,
-		{"Web files", []string{"*.html", "*.js", "*.css"}},
+		zenity.Filename(defaultName),
-		{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
+		zenity.FileFilters{
-	}.New())
+			{"Go files", []string{"*.go"}},
-
+			{"Web files", []string{"*.html", "*.js", "*.css"}},
-	if err != nil {
+			{"Image files", []string{"*.png", "*.gif", "*.ico", "*.jpg", "*.webp"}},
-		t.Error(err)
+		}.New())
-	} else {
+	// Output:
-		t.Logf("%#v", res)
-	}
 }
 
-func TestSelectDirectory(t *testing.T) {
+func ExampleSelectFile_directory() {
-	res, err := SelectFile(Directory, Filename(defaultPath))
+	zenity.SelectFile(
-
+		zenity.Filename(defaultPath),
-	if err != nil {
+		zenity.Directory)
-		t.Error(err)
+	// Output:
-	} else {
-		t.Logf("%#v", res)
-	}
 }
 
-func TestSelectDirectoryMultiple(t *testing.T) {
+func ExampleSelectFileMutiple_directory() {
-	res, err := SelectFileMutiple(Directory, Filename(defaultPath))
+	zenity.SelectFileMutiple(
-
+		zenity.Filename(defaultPath),
-	if err != nil {
+		zenity.Directory)
-		t.Error(err)
+	// Output:
-	} else {
-		t.Logf("%#v", res)
-	}
 }

file_unix.go

@@ -10,6 +10,11 @@ import (
 	"github.com/ncruces/zenity/internal/zen"
 )
 
+// Display file selection dialog.
+//
+// Returns an empty string on cancel.
+//
+// Valid options: Title, Directory, Filename, FileFilters.
 func SelectFile(options ...Option) (string, error) {
 	opts := optsParse(options)
 
@@ -38,6 +43,11 @@ func SelectFile(options ...Option) (string, error) {
 	return string(out), nil
 }
 
+// Display multiple file selection dialog.
+//
+// Returns a nil slice on cancel.
+//
+// Valid options: Title, Directory, Filename, FileFilters.
 func SelectFileMutiple(options ...Option) ([]string, error) {
 	opts := optsParse(options)
 
@@ -66,6 +76,11 @@ func SelectFileMutiple(options ...Option) ([]string, error) {
 	return strings.Split(string(out), cmd.Separator), nil
 }
 
+// Display save file selection dialog.
+//
+// Returns an empty string on cancel.
+//
+// Valid options: Title, Filename, ConfirmOverwrite, FileFilters.
 func SelectFileSave(options ...Option) (string, error) {
 	opts := optsParse(options)
 

msg_test.go

@@ -1,43 +1,31 @@
-package zenity
+package zenity_test
 
-import "testing"
+import "github.com/ncruces/zenity"
 
-func TestError(t *testing.T) {
+func ExampleError() {
-	res, err := Error("An error has occured.", Title("Error"), Icon(ErrorIcon))
+	zenity.Error("An error has occured.",
-
+		zenity.Title("Error"),
-	if err != nil {
+		zenity.Icon(zenity.ErrorIcon))
-		t.Error(err)
+	// Output:
-	} else {
-		t.Logf("%#v", res)
-	}
 }
 
-func TestInfo(t *testing.T) {
+func ExampleInfo() {
-	res, err := Info("All updates are complete.", Title("Information"), Icon(InfoIcon))
+	zenity.Info("All updates are complete.",
-
+		zenity.Title("Information"),
-	if err != nil {
+		zenity.Icon(zenity.InfoIcon))
-		t.Error(err)
+	// Output:
-	} else {
-		t.Logf("%#v", res)
-	}
 }
 
-func TestWarning(t *testing.T) {
+func ExampleWarning() {
-	res, err := Warning("Are you sure you want to proceed?", Title("Warning"), Icon(WarningIcon))
+	zenity.Warning("Are you sure you want to proceed?",
-
+		zenity.Title("Warning"),
-	if err != nil {
+		zenity.Icon(zenity.WarningIcon))
-		t.Error(err)
+	// Output:
-	} else {
-		t.Logf("%#v", res)
-	}
 }
 
-func TestQuestion(t *testing.T) {
+func ExampleQuestion() {
-	res, err := Question("Are you sure you want to proceed?", Title("Question"), Icon(QuestionIcon))
+	zenity.Question("Are you sure you want to proceed?",
-
+		zenity.Title("Question"),
-	if err != nil {
+		zenity.Icon(zenity.QuestionIcon))
-		t.Error(err)
+	// Output:
-	} else {
-		t.Logf("%#v", res)
-	}
 }

msg_unix.go

@@ -8,18 +8,39 @@ import (
 	"github.com/ncruces/zenity/internal/zen"
 )
 
+// Display error dialog.
+//
+// Returns true on OK, false on dismiss, or ErrExtraButton.
+//
+// Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.
 func Error(text string, options ...Option) (bool, error) {
 	return message("--error", text, options)
 }
 
+// Display info dialog.
+//
+// Returns true on OK, false on dismiss, or ErrExtraButton.
+//
+// Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.
 func Info(text string, options ...Option) (bool, error) {
 	return message("--info", text, options)
 }
 
+// Display question dialog.
+//
+// Returns true on OK, false on Cancel, or ErrExtraButton.
+//
+// Valid options: Title, Icon, OKLabel, CancelLabel, ExtraButton, NoWrap,
+// Ellipsize, DefaultCancel.
 func Question(text string, options ...Option) (bool, error) {
 	return message("--question", text, options)
 }
 
+// Display warning dialog.
+//
+// Returns true on OK, false on dismiss, or ErrExtraButton.
+//
+// Valid options: Title, Icon, OKLabel, ExtraButton, NoWrap, Ellipsize.
 func Warning(text string, options ...Option) (bool, error) {
 	return message("--warning", text, options)
 }

zenity.go

@@ -32,6 +32,7 @@ type options struct {
 	defcancel bool
 }
 
+// Options are arguments you pass to dialog functions to customize their behavior.
 type Option func(*options)
 
 func optsParse(options []Option) (res options) {
@@ -43,6 +44,7 @@ func optsParse(options []Option) (res options) {
 
 // General options
 
+// Option to set the dialog title.
 func Title(title string) Option {
 	return func(o *options) {
 		o.title = title
@@ -51,27 +53,41 @@ func Title(title string) Option {
 
 // File selection options
 
+// Option to set the filename.
+//
+// You can specify a file name, a directory path, or both.
+// Specifying a file name, makes it the default selected file.
+// Specifying a directory path, make it the default dialog location.
 func Filename(filename string) Option {
 	return func(o *options) {
 		o.filename = filename
 	}
 }
 
+// Option to activate directory-only selection.
 func Directory(o *options) {
 	o.directory = true
 }
 
+// Option to confirm file selection if filename already exists.
 func ConfirmOverwrite(o *options) {
 	o.overwrite = true
 }
 
+// FileFilter encapsulates a filename filter.
 type FileFilter struct {
-	Name     string
+	Name     string   // display string that describes the filter (optional)
-	Patterns []string
+	Patterns []string // filter patterns for the display string
 }
 
+// FileFilters is a list of filename filters.
+//
+// macOS hides filename filters from the user,
+// and only supports filtering by extension (or "type").
+// We make an effort to convert any "*.EXT" like patterns.
 type FileFilters []FileFilter
 
+// Creates Option to set the filename filter list.
 func (f FileFilters) New() Option {
 	return func(o *options) {
 		o.filters = f
@@ -80,6 +96,7 @@ func (f FileFilters) New() Option {
 
 // Message options
 
+// MessageIcon is the enumeration for message dialog icons.
 type MessageIcon int
 
 const (
@@ -89,38 +106,45 @@ const (
 	WarningIcon
 )
 
+// Option to set the dialog icon.
 func Icon(icon MessageIcon) Option {
 	return func(o *options) {
 		o.icon = icon
 	}
 }
 
+// Option to set the label of the OK button.
 func OKLabel(ok string) Option {
 	return func(o *options) {
 		o.ok = ok
 	}
 }
 
+// Option to set the label of the Cancel button.
 func CancelLabel(cancel string) Option {
 	return func(o *options) {
 		o.cancel = cancel
 	}
 }
 
+// Option to add an extra button.
 func ExtraButton(extra string) Option {
 	return func(o *options) {
 		o.extra = extra
 	}
 }
 
+// Option to disable enable text wrapping.
 func NoWrap(o *options) {
 	o.nowrap = true
 }
 
+// Option to enable ellipsizing in the dialog text.
 func Ellipsize(o *options) {
 	o.ellipsize = true
 }
 
+// Option to give Cancel button focus by default.
 func DefaultCancel(o *options) {
 	o.defcancel = true
 }