docs: add doc comments

args.go

@@ -6,6 +6,24 @@ import (
 	"strings"
 )
 
+// getOpts parses command-line arguments and returns an Options struct populated with the parsed values.
+// It supports various flags to customize the behavior of the program, such as reading from stdin,
+// specifying a file, setting the charset, and more. If an invalid charset is provided, the function
+// prints an error message and exits the program.
+//
+// Supported flags:
+//
+//	-h, --help            : Display help text and exit.
+//	-, --stdin            : Read input from stdin.
+//	-f, --file <filename> : Read input from the specified file.
+//	-c, --charset <name>  : Set the charset (valid values are "utf-8" and "ascii").
+//	-s, --trailing-slash  : Enable trailing slash in output.
+//	-p, --full-path       : Enable full path in output.
+//	-D, --no-root-dot     : Disable the root dot in output.
+//
+// Returns:
+//
+//	Options - A struct containing the parsed options.
 func getOpts() Options {
 	opts := Options{false, "", strings.Builder{}, "utf-8", false, false, true}
 	args := os.Args[1:]

describe.go

@@ -5,6 +5,12 @@ import (
 	"strings"
 )
 
+// helpText generates and returns a strings.Builder containing the help text for the program.
+// The help text includes usage instructions and descriptions of the available command-line options.
+//
+// Returns:
+//
+//	strings.Builder - A builder containing the formatted help text.
 func helpText() strings.Builder {
 	LE := getLE()
 	var builder strings.Builder
@@ -22,6 +28,18 @@ func helpText() strings.Builder {
 	return builder
 }
 
+// describeTree generates a string representation of the tree structure starting from the given node.
+// It recursively traverses the tree and collects lines representing each node and its children.
+// The function ensures that blank lines are removed from the final output.
+//
+// Parameters:
+//
+//	node - The root node of the tree to describe.
+//	opts - A pointer to an Options struct that specifies formatting options.
+//
+// Returns:
+//
+//	string - A string representation of the tree structure.
 func describeTree(node *Node, opts *Options) string {
 	lines := []string{getTreeLine(node, opts)}
 	LE := getLE()
@@ -45,6 +63,19 @@ func describeTree(node *Node, opts *Options) string {
 	return strings.Join(nonBlankLines, LE)
 }
 
+// getPrefixes returns the appropriate tree drawing characters based on the specified charset in options.
+// It supports both ASCII and UTF-8 character sets.
+//
+// Parameters:
+//
+//	opts - A pointer to an Options struct that specifies the charset.
+//
+// Returns:
+//
+//	string - The prefix for a child node.
+//	string - The prefix for the last child node.
+//	string - The prefix for a directory node.
+//	string - The prefix for an empty node.
 func getPrefixes(opts *Options) (string, string, string, string) {
 	if opts.charset == "ascii" {
 		return ASCII_CHILD, ASCII_LAST_CHILD, ASCII_DIRECTORY, ASCII_EMPTY
@@ -52,6 +83,12 @@ func getPrefixes(opts *Options) (string, string, string, string) {
 	return UTF8_CHILD, UTF8_LAST_CHILD, UTF8_DIRECTORY, UTF8_EMPTY
 }
 
+// getLE returns the appropriate line ending based on the operating system.
+// It returns "\r\n" for Windows and "\n" for Unix-based systems.
+//
+// Returns:
+//
+//	string - The line ending string.
 func getLE() string {
 	if os.IsPathSeparator('\\') {
 		return LE_WIN
@@ -59,6 +96,19 @@ func getLE() string {
 	return LE_UNIX
 }
 
+// getTreeLine generates a string representing a single line of the tree structure for the given node.
+// It constructs the line by adding appropriate tree drawing characters based on the node's position
+// and the specified options. The function handles the root node, child nodes, and last child nodes
+// differently to ensure the correct tree structure is represented.
+//
+// Parameters:
+//
+//	node - The node for which to generate the tree line.
+//	opts - A pointer to an Options struct that specifies formatting options.
+//
+// Returns:
+//
+//	string - A string representing the tree line for the given node.
 func getTreeLine(node *Node, opts *Options) string {
 	if node.parent == nil {
 		if opts.rootDot {
@@ -97,6 +147,18 @@ func getTreeLine(node *Node, opts *Options) string {
 	return removePrefix(str, opts)
 }
 
+// getName generates the name of the node, optionally appending a trailing slash if the node has children
+// and the trailingSlash option is enabled. If the fullPath option is enabled, it recursively constructs
+// the full path of the node.
+//
+// Parameters:
+//
+//	node - The node for which to generate the name.
+//	opts - A pointer to an Options struct that specifies formatting options.
+//
+// Returns:
+//
+//	string - The generated name of the node.
 func getName(node *Node, opts *Options) string {
 	var chunks strings.Builder
 
@@ -116,10 +178,30 @@ func getName(node *Node, opts *Options) string {
 	return str
 }
 
+// isLastChild checks if the given node is the last child of its parent.
+//
+// Parameters:
+//
+//	node - The node to check.
+//
+// Returns:
+//
+//	bool - True if the node is the last child, false otherwise.
 func isLastChild(node *Node) bool {
 	return node.parent != nil && node.parent.children[len(node.parent.children)-1] == node
 }
 
+// removePrefix removes the tree drawing prefix from the given string based on the specified options.
+// It ensures that the correct prefix is removed to maintain the tree structure.
+//
+// Parameters:
+//
+//	str - The string from which to remove the prefix.
+//	opts - A pointer to an Options struct that specifies the charset.
+//
+// Returns:
+//
+//	string - The string with the prefix removed.
 func removePrefix(str string, opts *Options) string {
 	CHILD, LAST_CHILD, DIRECTORY, EMPTY := getPrefixes(opts)
 

parse.go

@@ -7,6 +7,18 @@ import (
 	"strings"
 )
 
+// parseDepth calculates the depth of a line based on its leading whitespace characters.
+// The depth is determined by counting the number of leading spaces and tabs.
+// If an indent size is provided, the depth is divided by the indent size to normalize it.
+//
+// Parameters:
+//
+//	line - The input string line whose depth is to be calculated.
+//	indentSize - The size of the indentation to be used for normalization.
+//
+// Returns:
+//
+//	int - The calculated depth of the line.
 func parseDepth(line string, indentSize int) int {
 	depth := 0
 	for j := 0; j < len(line); j++ {
@@ -21,6 +33,17 @@ func parseDepth(line string, indentSize int) int {
 	return depth
 }
 
+// parseInput parses a string input representing a tree structure and returns the root node of the tree.
+// The input string should use indentation to represent the depth of each node in the tree.
+// The function handles different line endings and adjusts the indentation size based on the input.
+//
+// Parameters:
+//
+//	input - A string representing the tree structure with nodes and indentation.
+//
+// Returns:
+//
+//	*Node - The root node of the parsed tree structure.
 func parseInput(input string) *Node {
 	input = strings.Replace(input, "\r", "", -1)
 	root := &Node{".", 0, []*Node{}, nil}
@@ -55,6 +78,19 @@ func parseInput(input string) *Node {
 	return root
 }
 
+// parseRawInput reads input based on the provided options and returns it as a strings.Builder.
+// It can read from stdin, a file, or an extra string provided in the options.
+// If an error occurs during reading, it returns the error with a description and an error code.
+//
+// Parameters:
+//
+//	opts - A pointer to an Options struct that specifies the input source.
+//
+// Returns:
+//
+//	strings.Builder - The input read from the specified source.
+//	error - An error object if an error occurred, otherwise nil.
+//	int - An error code: 0 for success, 1 for reading errors, 2 for missing input source.
 func parseRawInput(opts *Options) (strings.Builder, error, int) {
 	var input strings.Builder