Documentation updates

Variables.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 )
 
+// Colors enumerates some basic, commonly used colors.
 var Colors map[string]Color = map[string]Color{
 	"Black": &RGB{0, 0, 0},
 	"Gray":  &RGB{128, 128, 128},
@@ -11,19 +12,27 @@ var Colors map[string]Color = map[string]Color{
 }
 
 // ModeEnum determines how aggressively the package will attempt to sync with Photoshop.
+// Loading Photoshop files from scratch takes a long time, so the package saves
+// the state of the document in a JSON file in the /data folder whenever you call
+// Document.Dump(). ModeEnum tells the program how trustworthy that file is.
 type ModeEnum int
 
 // Holds the current mode.
 var Mode ModeEnum
 
-// Fast mode never checks layers before returning.
+// Fast mode skips all verification. Use Fast mode only when certain that the
+// .psd file hasn't changed since the last time Document.Dump() was called.
 const Fast ModeEnum = 2
 
-// Normal Mode Always checks to see if layers are up to date
-// before returning them.
+// Normal Mode only verifies layers as they are operated on. The first time a
+// layer's properties would be checked, it first overwrites the data from the
+// Dump with data pulled directly from Photoshop. This allows you to quickly
+// load documents in their current form.
 const Normal ModeEnum = 0
 
-// Safe Mode Always loads the document from scratch. (Very Slow)
+// Safe Mode always loads the document from scratch, ignoring any dumped data.
+// (Very Slow). If a function panics due to outdated data, often times re-running
+// the function in safe mode is enough to re-mediate it.
 const Safe ModeEnum = 1
 
 // PSSaveOptions is an enum for options when closing a document.

colors.go

@@ -26,7 +26,7 @@ func Compare(a, b Color) Color {
 	return b
 }
 
-// RGB is a color in RGB format. It fulfills the Color interface.
+// RGB is a color in RGB format. It implements the Color interface.
 type RGB struct {
 	Red   int
 	Green int
@@ -43,7 +43,7 @@ func (r RGB) Hex() []uint8 {
 	return make([]uint8, 6)
 }
 
-// Hex is a color in hexadecimal format. It fulfills the Color interface.
+// Hex is a color in hexadecimal format. It implements the Color interface.
 type Hex []uint8
 
 func (h Hex) RGB() [3]int {

ps.go

@@ -1,9 +1,7 @@
 // Package ps is a rudimentary API between Adobe Photoshop CS5 and Golang.
+// The interaction between the two is implemented using Javascript/VBScript.
 //
-// Most of the interaction between the two is implemented via
-// Javascript and/or VBS/Applescript.
-//
-// Currently only works with CS5 on Windows.
+// Currently only supports Photoshop CS5 Windows x86_64.
 package ps
 
 import (
@@ -19,8 +17,11 @@ import (
 	"strings"
 )
 
-var Cmd string
-var Opts string
+// The name of the program that runs scripts on this OS.
+var scmd string
+
+// The options we need to pass to scmd.
+var opts string
 var pkgpath string
 
 func init() {
@@ -28,10 +29,10 @@ func init() {
 	pkgpath = filepath.Dir(file)
 	switch runtime.GOOS {
 	case "windows":
-		Cmd = "cscript.exe"
-		Opts = "/nologo"
+		scmd = "cscript.exe"
+		opts = "/nologo"
 	case "darwin":
-		Cmd = "osacript"
+		scmd = "osacript"
 	}
 }
 
@@ -41,7 +42,7 @@ func Start() error {
 	return err
 }
 
-// Close closes the active document in Photoshop.
+// Close closes the active document in Photoshop, using the given save option.
 func Close(save PSSaveOptions) error {
 	_, err := run("close", save.String())
 	return err
@@ -49,7 +50,7 @@ func Close(save PSSaveOptions) error {
 
 // Open opens a Photoshop document with the specified path.
 // If Photoshop is not currently running, it is started before
-// opening the document
+// opening the document.
 func Open(path string) error {
 	_, err := run("open", path)
 	return err
@@ -68,8 +69,8 @@ func SaveAs(path string) error {
 }
 
 // DoJs runs a Photoshop Javascript script file (.jsx) from the specified location.
-// It can't directly return output, so instead the scripts write their output to
-// a temporary file, whose contents is then read and returned.
+// It can't directly return output, so instead the script must write their output to
+// a temporary file ($TEMP/js_out.txt), whose contents is then read and returned.
 func DoJs(path string, args ...string) (out []byte, err error) {
 	// Temp file for js to output to.
 	outpath := filepath.Join(os.Getenv("TEMP"), "js_out.txt")
@@ -100,7 +101,7 @@ func DoJs(path string, args ...string) (out []byte, err error) {
 // signals that they are ready (by pushing enter).
 //
 // Useful for when you need to do something by hand in the middle of an
-// otherwise automated process.
+// otherwise automated process. (i.e. loading a dataset).
 func Wait(msg string) {
 	fmt.Print(msg)
 	var input string
@@ -125,14 +126,14 @@ func run(name string, args ...string) ([]byte, error) {
 	}
 
 	if strings.Contains(name, "dojs") {
-		args = append([]string{Opts, filepath.Join(pkgpath, "scripts", name)},
+		args = append([]string{opts, filepath.Join(pkgpath, "scripts", name)},
 			args[0],
 			fmt.Sprintf("%s", strings.Join(args[1:], ",")),
 		)
 	} else {
-		args = append([]string{Opts, filepath.Join(pkgpath, "scripts", name)}, args...)
+		args = append([]string{opts, filepath.Join(pkgpath, "scripts", name)}, args...)
 	}
-	cmd := exec.Command(Cmd, args...)
+	cmd := exec.Command(scmd, args...)
 	cmd.Stdout = &out
 	cmd.Stderr = &errs
 	err := cmd.Run()
@@ -142,7 +143,7 @@ func run(name string, args ...string) ([]byte, error) {
 	return out.Bytes(), nil
 }
 
-// DoAction runs the Photoshop action with name from set.
+// DoAction runs the Photoshop Action "name" from the Action Set "set".
 func DoAction(set, name string) error {
 	_, err := run("action", set, name)
 	return err
@@ -151,15 +152,18 @@ func DoAction(set, name string) error {
 // ApplyDataset fills out a template file with information
 // from a given dataset (csv) file. It is important to note that running this
 // function will change data in the Photoshop document, but will not update
-// data in the Go Document struct (if any); you will have to implement syncing
+// data in the Go Document struct- you will have to implement syncing
 // them yourself.
-func ApplyDataset(name string) ([]byte, error) {
-	return DoJs("applyDataset.jsx", name)
+func ApplyDataset(name string) error {
+	_, err := DoJs("applyDataset.jsx", name)
+	return err
 }
 
 // JSLayer "compiles" Javascript code to get an ArtLayer with the given path.
 // The output always ends with a semicolon, so if you want to access a specific
-// property of the layer, you'll have to trim the output before concatenating
+// property of the layer, you'll have to trim the output before concatenating.
+//
+// TODO: get rid of the semicolon.
 func JSLayer(path string, art ...bool) string {
 	path = strings.TrimLeft(path, "/")
 	pth := strings.Split(path, "/")

structs.go

@@ -179,7 +179,8 @@ func (d *Document) Dump() {
 }
 
 // ArtLayer reflects certain values from an Art Layer in a Photoshop document.
-// TODO: Make TextLayer a subclass of ArtLayer
+//
+// TODO: Make TextLayer a subclass of ArtLayer.
 type ArtLayer struct {
 	name    string    // The layer's name.
 	Text    *string   // The contents of a text layer.
@@ -219,7 +220,7 @@ func (a *ArtLayer) SetText(txt string) {
 	a.Refresh()
 }
 
-// MarshalJSON fulfills the json.Marshaler interface, allowing the ArtLayer to be
+// MarshalJSON implements the json.Marshaler interface, allowing the ArtLayer to be
 // saved to disk in JSON format.
 func (a *ArtLayer) MarshalJSON() ([]byte, error) {
 	// txt := strings.Replace(*a.Text, "\r", "\\r", -1)
@@ -370,6 +371,7 @@ func (a *ArtLayer) Path() string {
 	return fmt.Sprintf("%s%s", a.parent.Path(), a.name)
 }
 
+// TODO: Documentation for Format()
 func (a *ArtLayer) Format(start, end int, font, style string) {
 	if !a.Visible() {
 		return
@@ -383,7 +385,7 @@ func (a *ArtLayer) Format(start, end int, font, style string) {
 
 // Layer returns an ArtLayer from the active document given a specified
 // path string.
-func Layer(path string) (ArtLayer, error) {
+func layer(path string) (ArtLayer, error) {
 	byt, err := DoJs("getLayer.jsx", JSLayer(path))
 	var out ArtLayer
 	err = json.Unmarshal(byt, &out)
@@ -453,7 +455,7 @@ func (a *ArtLayer) SetPos(x, y int, bound string) {
 }
 
 func (a *ArtLayer) Refresh() error {
-	tmp, err := Layer(a.Path())
+	tmp, err := layer(a.Path())
 	if err != nil {
 		return err
 	}