Added extensive documentation

cmd/issues.go

@@ -21,7 +21,6 @@ func main() {
 		os.Exit(1)
 	}
 
-	// if issues.IsIssue(arg[0]) {
 	p := tea.NewProgram(
 		issues.Model{Path: arg[0]},
 		tea.WithAltScreen(), // use the full size of the terminal in its "alternate screen buffer"
@@ -32,8 +31,4 @@ func main() {
 		fmt.Println("could not run program:", err)
 		os.Exit(1)
 	}
-	// } else if issues.IsIssueCollection(arg[0]) {
-	// 	fmt.Println("Collection of Issues:", arg)
-	// 	os.Exit(0)
-	// }
 }

io.go

@@ -1,3 +1,27 @@
+// This package defines several top level IO functions for interacting with
+// issues and collections of issues.
+//
+// Examples:
+//
+//	To check if a folder is spec compliant:
+//		...
+//		if issues.IsIssue(path_to_folder) {
+//			process_issue(path_to_folder)
+//		}
+//
+//	Additionally, to check if a folder is a collection of spec compliant issues:
+//		...
+//		if issues.IsIssueCollection(path_to_folder) {
+//			process_collection(path_to_folder)
+//		}
+//
+//	To write an [Issue] object to disk:
+//		...
+//		// NOT IMPLEMENTED
+//
+//	To remove an [Issue] object from disk:
+//		...
+//		// NOT IMPLEMENTED
 package issues
 
 import (

issue.go

@@ -1,4 +1,97 @@
-// Data and interface definitions for bugs
+// The package provides a series of data structures for interaction with and
+// interpolation of issues.
+//
+// At its most basic level, an issue is a simple collection of strings of text,
+// with no specific implementation requirements, aside from their existance.
+// As per spec, issues are simply folders with specific named plain text files.
+// Two of those files require the files to have data, while the rest do not require
+// associated data.
+//
+// The only two mandatory files to pass spec are the "description" file
+// ($ISSUE_PATH/description) and the "status" file ($ISSUE_PATH/status):
+//
+//   - the description file:
+//
+//     An issue's description should have, at the least, a descriptive title.
+//     The authors recommend following the Git Commit basic style guidelines.
+//
+//   - the status file:
+//
+//     An issue's status file should contain at minimum a human readable one
+//     line description of the status' current state. For example, "open" or
+//     "closed." The authors recommend using a semicolon to separate assignments
+//     or related goals. For example, "assigned:arianagiroux" or "bug:critical".
+//
+// These couplings of files and subsequent file data are represented via the Field
+// struct. Each Field struct has the following fields:
+//
+//   - The file's path (Field.Path), relative to the issue's root path, and
+//
+//   - The file's contents (Field.Data)
+//
+// Example:
+//
+//	 ...
+//		// define a new Field
+//		description := Field.New(data_from_file, path_relative_to_root)
+//		// OR
+//		description := Field.NewFromPath(path_to_file) // NOT IMPLEMENTED AS OF 0.0.3
+//
+// The spec additionally outlines optional implementations of "tags" and
+// "blockers". What the developer uses these for is up to them. Both are treated
+// similarly, where tags are located in a directory named "tags", and blockers
+// are located in a directory named "blockedby". The spec does not outline any
+// use for the content of these plain files, and (as of 0.0.3) issues does not
+// load the data from these files.
+//
+// Note: the files within the "blockedby" folder are referred to as both "Blockers"
+// and "Blockedby" interchangeably throughout the package, where applicable.
+//
+// The package defines the struct "VariadicField" to facilitate both "tags" and
+// "blockers". Theoretically, it can facilitate any folder that matches the
+// restraints as outlined by the spec. A VariadicField is, at its core, a slice
+// of Field objects with an associated path. This is ensure that it's underlying
+// []Field object is associated with a path on disk.
+//
+// Example:
+//
+//	...
+//	// define some Fields
+//	fields := []Field{{path:"tag1"}, {path:"tag2"}}
+//	// define a new VariadicField
+//	tags := VariadicField.New(fields, "/tags")
+//	// OR
+//	tags := VariadicField{Fields:fields, Path:"/tags"}
+//	// OR
+//	tags := VariadicField{path:"/tags"}.NewFromPath("an_issue/tags")
+//
+// The Issue struct utilizes both Field and VariadicField structs to represent
+// a full spec compliant issue. While it is possible to instantiate the struct
+// directly, it is not recommended. The struct provides two constructor functions,
+// which handles parsing spec confoming issue "titles" (read: root issue path)
+// as human readable strings.
+//
+// Example:
+//
+//	...
+//	// data prep
+//	description := Field{Path:"/description", Data:"a descriptive blurb"}
+//	status := Field{Path:"/status", Data:"open"}
+//	tags := VariadicField{Path:"/tags"}
+//	blockers := VariadicField{Path:"/blockedby"}
+//	path := "issues/an_issue"
+//	...
+//	// new Issue with custom title
+//	customTitleIssue := Issue.New(Issue{}, "A Custom Title",
+//			description, status, tags, blockers, path)
+//	// new Issue, automatic title
+//	autoTitleIssue := Issue.New(Issue{}, "",
+//			description, status, tags, blockers, path)
+//	// new Issue from path on disk
+//	issueFromDisk := Issue.NewFroMPath(Issue{}, "issues/an_issue")
+//
+// Finally, the package defines a simple data structure for a collection of
+// issues: the "IssueCollection". This is a simple slice of Issues ([]Issue).
 package issues
 
 import (

tui.go

@@ -1,3 +1,6 @@
+// The package defines an extensible TUI via the bubbletea framework.
+//
+// While the package remains in v0.0.X releases, this TUI may be undocumented.
 package issues
 
 import (