From f92bb18c30800942d54002480c63c242d308f258 Mon Sep 17 00:00:00 2001 From: Unknown Date: Tue, 24 Apr 2018 21:11:34 -0400 Subject: [PATCH] Documentation updates --- Variables.go | 17 +++++++++++++---- colors.go | 4 ++-- ps.go | 48 ++++++++++++++++++++++++++---------------------- structs.go | 10 ++++++---- 4 files changed, 47 insertions(+), 32 deletions(-) diff --git a/Variables.go b/Variables.go index ce6d7e1..567eb48 100644 --- a/Variables.go +++ b/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. diff --git a/colors.go b/colors.go index ec9fba9..0586a73 100644 --- a/colors.go +++ b/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 { diff --git a/ps.go b/ps.go index 93d7090..482d410 100644 --- a/ps.go +++ b/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, "/") diff --git a/structs.go b/structs.go index f29edfb..1768b8d 100644 --- a/structs.go +++ b/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 }