examples: refactored and documented all examples

_examples/area/center/main.go

@@ -7,12 +7,20 @@ import (
 )
 
 func main() {
+	// Start a new default area in the center of the terminal.
+	// The Start() function returns the created area and an error.
 	area, _ := pterm.DefaultArea.WithCenter().Start()
 
+	// Loop 5 times to simulate a dynamic update.
 	for i := 0; i < 5; i++ {
+		// Update the content of the area with the current count.
+		// The Sprintf function is used to format the string.
 		area.Update(pterm.Sprintf("Current count: %d\nAreas can update their content dynamically!", i))
+
+		// Pause for a second to simulate a time-consuming task.
 		time.Sleep(time.Second)
 	}
 
+	// Stop the area after all updates are done.
 	area.Stop()
 }

_examples/area/default/main.go

@@ -7,12 +7,21 @@ import (
 )
 
 func main() {
+	// Start a new default area and get a reference to it.
+	// The second return value is an error which is ignored here.
 	area, _ := pterm.DefaultArea.Start()
 
+	// Loop 5 times
 	for i := 0; i < 5; i++ {
+		// Update the content of the area dynamically.
+		// Here we're just displaying the current count.
 		area.Update(pterm.Sprintf("Current count: %d\nAreas can update their content dynamically!", i))
+
+		// Pause for a second before the next update.
 		time.Sleep(time.Second)
 	}
 
+	// Stop the area after all updates are done.
+	// This will clean up and free resources used by the area.
 	area.Stop()
 }

_examples/area/demo/main.go

@@ -4,17 +4,36 @@ import (
 	"time"
 
 	"github.com/pterm/pterm"
+	"github.com/pterm/pterm/putils"
 )
 
 func main() {
+	// Print an informational message using PTerm's Info printer.
+	// This message will stay in place while the area updates.
 	pterm.Info.Println("The previous text will stay in place, while the area updates.")
-	pterm.Print("\n\n") // Add two new lines as spacer.
 
-	area, _ := pterm.DefaultArea.WithCenter().Start() // Start the Area printer, with the Center option.
+	// Print two new lines as spacer.
+	pterm.Print("\n\n")
+
+	// Start the Area printer from PTerm's DefaultArea, with the Center option.
+	// The Area printer allows us to update a specific area of the console output.
+	// The returned 'area' object is used to control the area updates.
+	area, _ := pterm.DefaultArea.WithCenter().Start()
+
+	// Loop 10 times to update the area with the current time.
 	for i := 0; i < 10; i++ {
-		str, _ := pterm.DefaultBigText.WithLetters(pterm.NewLettersFromString(time.Now().Format("15:04:05"))).Srender() // Save current time in str.
-		area.Update(str)                                                                                                // Update Area contents.
+		// Get the current time, format it as "15:04:05" (hour:minute:second), and convert it to a string.
+		// Then, create a BigText from the time string using PTerm's DefaultBigText and putils NewLettersFromString.
+		// The Srender() function is used to save the BigText as a string.
+		str, _ := pterm.DefaultBigText.WithLetters(putils.NewLettersFromString(time.Now().Format("15:04:05"))).Srender()
+
+		// Update the Area contents with the current time string.
+		area.Update(str)
+
+		// Sleep for a second before the next update.
 		time.Sleep(time.Second)
 	}
+
+	// Stop the Area printer after all updates are done.
 	area.Stop()
 }

_examples/area/dynamic-chart/main.go

@@ -7,22 +7,34 @@ import (
 )
 
 func main() {
+	// Start a new fullscreen centered area.
+	// This area will be used to display the bar chart.
 	area, _ := pterm.DefaultArea.WithFullscreen().WithCenter().Start()
+	// Ensure the area stops updating when we're done.
 	defer area.Stop()
 
+	// Loop to update the bar chart 10 times.
 	for i := 0; i < 10; i++ {
+		// Create a new bar chart with dynamic bars.
+		// The bars will change based on the current iteration.
 		barchart := pterm.DefaultBarChart.WithBars(dynamicBars(i))
+		// Render the bar chart to a string.
+		// This string will be used to update the area.
 		content, _ := barchart.Srender()
+		// Update the area with the new bar chart.
 		area.Update(content)
+		// Wait for half a second before the next update.
 		time.Sleep(500 * time.Millisecond)
 	}
 }
 
+// dynamicBars generates a set of bars for the bar chart.
+// The bars will change based on the current iteration.
 func dynamicBars(i int) pterm.Bars {
 	return pterm.Bars{
-		{Label: "A", Value: 10},
-		{Label: "B", Value: 20 * i},
-		{Label: "C", Value: 30},
-		{Label: "D", Value: 40 + i},
+		{Label: "A", Value: 10},     // A static bar.
+		{Label: "B", Value: 20 * i}, // A bar that grows with each iteration.
+		{Label: "C", Value: 30},     // Another static bar.
+		{Label: "D", Value: 40 + i}, // A bar that grows slowly with each iteration.
 	}
 }

_examples/area/fullscreen-center/main.go

@@ -7,12 +7,21 @@ import (
 )
 
 func main() {
+	// Initialize a new PTerm area with fullscreen and center options
+	// The Start() function returns the created area and an error (ignored here)
 	area, _ := pterm.DefaultArea.WithFullscreen().WithCenter().Start()
 
+	// Loop 5 times to demonstrate dynamic content update
 	for i := 0; i < 5; i++ {
+		// Update the content of the area with the current count
+		// The Sprintf function is used to format the string with the count
 		area.Update(pterm.Sprintf("Current count: %d\nAreas can update their content dynamically!", i))
+
+		// Pause for a second
 		time.Sleep(time.Second)
 	}
 
+	// Stop the area after all updates are done
+	// This will clear the area and return the terminal to its normal state
 	area.Stop()
 }

_examples/area/fullscreen/main.go

@@ -7,12 +7,20 @@ import (
 )
 
 func main() {
+	// Start a new fullscreen area. This will return an area instance and an error.
+	// The underscore (_) is used to ignore the error.
 	area, _ := pterm.DefaultArea.WithFullscreen().Start()
 
+	// Loop 5 times to update the area content.
 	for i := 0; i < 5; i++ {
+		// Update the content of the area with the current count.
+		// The Sprintf function is used to format the string.
 		area.Update(pterm.Sprintf("Current count: %d\nAreas can update their content dynamically!", i))
+
+		// Pause for a second before the next update.
 		time.Sleep(time.Second)
 	}
 
+	// Stop the area after all updates are done.
 	area.Stop()
 }

_examples/barchart/custom-height/main.go

@@ -3,7 +3,9 @@ package main
 import "github.com/pterm/pterm"
 
 func main() {
-	pterm.DefaultBarChart.WithBars([]pterm.Bar{
+	// Define a slice of Bar structs. Each struct represents a bar in the chart.
+	// The Label field is the name of the bar and the Value field is the height of the bar.
+	bars := []pterm.Bar{
 		{Label: "A", Value: 10},
 		{Label: "B", Value: 20},
 		{Label: "C", Value: 30},
@@ -13,5 +15,11 @@ func main() {
 		{Label: "G", Value: 30},
 		{Label: "H", Value: 20},
 		{Label: "I", Value: 10},
-	}).WithHeight(5).Render()
+	}
+
+	// Create and render a bar chart with the defined bars and a height of 5.
+	// The WithBars method is used to set the bars of the chart.
+	// The WithHeight method is used to set the height of the chart.
+	// The Render method is used to display the chart in the terminal.
+	pterm.DefaultBarChart.WithBars(bars).WithHeight(5).Render()
 }

_examples/barchart/custom-width/main.go

@@ -3,7 +3,8 @@ package main
 import "github.com/pterm/pterm"
 
 func main() {
-	pterm.DefaultBarChart.WithBars([]pterm.Bar{
+	// Define the data for the bar chart
+	barData := []pterm.Bar{
 		{Label: "A", Value: 10},
 		{Label: "B", Value: 20},
 		{Label: "C", Value: 30},
@@ -13,5 +14,10 @@ func main() {
 		{Label: "G", Value: 30},
 		{Label: "H", Value: 20},
 		{Label: "I", Value: 10},
-	}).WithHorizontal().WithWidth(5).Render()
+	}
+
+	// Create a bar chart with the defined data
+	// The chart is horizontal and has a width of 5
+	// The Render() function is called to display the chart
+	pterm.DefaultBarChart.WithBars(barData).WithHorizontal().WithWidth(5).Render()
 }

_examples/barchart/default/main.go

@@ -3,7 +3,9 @@ package main
 import "github.com/pterm/pterm"
 
 func main() {
-	pterm.DefaultBarChart.WithBars([]pterm.Bar{
+	// Define the data for the bar chart. Each bar is represented by a `pterm.Bar` struct.
+	// The `Label` field represents the label of the bar, and the `Value` field represents the value of the bar.
+	bars := []pterm.Bar{
 		{Label: "A", Value: 10},
 		{Label: "B", Value: 20},
 		{Label: "C", Value: 30},
@@ -13,5 +15,10 @@ func main() {
 		{Label: "G", Value: 30},
 		{Label: "H", Value: 20},
 		{Label: "I", Value: 10},
-	}).Render()
+	}
+
+	// Use the `DefaultBarChart` from the `pterm` package to create a bar chart.
+	// The `WithBars` method is used to set the bars of the chart.
+	// The `Render` method is used to display the chart.
+	pterm.DefaultBarChart.WithBars(bars).Render()
 }

_examples/barchart/demo/main.go

@@ -5,22 +5,23 @@ import (
 )
 
 func main() {
-	positiveBars := pterm.Bars{
-		pterm.Bar{
-			Label: "Bar 1",
-			Value: 5,
-		},
-		pterm.Bar{
-			Label: "Bar 2",
-			Value: 3,
-		},
-		pterm.Bar{
-			Label: "Longer Label",
-			Value: 7,
-		},
+	// Define the bars for the chart
+	bars := []pterm.Bar{
+		{Label: "Bar 1", Value: 5},
+		{Label: "Bar 2", Value: 3},
+		{Label: "Longer Label", Value: 7},
 	}
 
+	// Print an informational message
 	pterm.Info.Println("Chart example with positive only values (bars use 100% of chart area)")
-	_ = pterm.DefaultBarChart.WithBars(positiveBars).Render()
-	_ = pterm.DefaultBarChart.WithHorizontal().WithBars(positiveBars).Render()
+
+	// Create a bar chart with the defined bars and render it
+	// The DefaultBarChart is used as a base, and the bars are added with the WithBars option
+	// The Render function is then called to display the chart
+	pterm.DefaultBarChart.WithBars(bars).Render()
+
+	// Create a horizontal bar chart with the defined bars and render it
+	// The DefaultBarChart is used as a base, the chart is made horizontal with the WithHorizontal option, and the bars are added with the WithBars option
+	// The Render function is then called to display the chart
+	pterm.DefaultBarChart.WithHorizontal().WithBars(bars).Render()
 }

_examples/barchart/horizontal-show-value/main.go

@@ -3,7 +3,8 @@ package main
 import "github.com/pterm/pterm"
 
 func main() {
-	pterm.DefaultBarChart.WithBars([]pterm.Bar{
+	// Define the data for the bar chart
+	barData := []pterm.Bar{
 		{Label: "A", Value: 10},
 		{Label: "B", Value: 20},
 		{Label: "C", Value: 30},
@@ -13,5 +14,10 @@ func main() {
 		{Label: "G", Value: 30},
 		{Label: "H", Value: 20},
 		{Label: "I", Value: 10},
-	}).WithHorizontal().WithShowValue().Render()
+	}
+
+	// Create a bar chart with the defined data
+	// The chart is horizontal and displays the value of each bar
+	// The Render() function is called to display the chart
+	pterm.DefaultBarChart.WithBars(barData).WithHorizontal().WithShowValue().Render()
 }

_examples/barchart/horizontal/main.go

@@ -3,7 +3,8 @@ package main
 import "github.com/pterm/pterm"
 
 func main() {
-	pterm.DefaultBarChart.WithBars([]pterm.Bar{
+	// Define the data for the bar chart
+	bars := []pterm.Bar{
 		{Label: "A", Value: 10},
 		{Label: "B", Value: 20},
 		{Label: "C", Value: 30},
@@ -13,5 +14,10 @@ func main() {
 		{Label: "G", Value: 30},
 		{Label: "H", Value: 20},
 		{Label: "I", Value: 10},
-	}).WithHorizontal().Render()
+	}
+
+	// Create a bar chart with the defined data
+	// The chart is displayed horizontally
+	// The Render() function is called to display the chart
+	pterm.DefaultBarChart.WithBars(bars).WithHorizontal().Render()
 }

_examples/barchart/mixed-values/main.go

@@ -5,30 +5,27 @@ import (
 )
 
 func main() {
-	mixedBars := pterm.Bars{
-		pterm.Bar{
-			Label: "Bar 1",
-			Value: 2,
-		},
-		pterm.Bar{
-			Label: "Bar 2",
-			Value: -3,
-		},
-		pterm.Bar{
-			Label: "Bar 3",
-			Value: -2,
-		},
-		pterm.Bar{
-			Label: "Bar 4",
-			Value: 5,
-		},
-		pterm.Bar{
-			Label: "Longer Label",
-			Value: 7,
-		},
+	// Define a set of bars for the chart.
+	// Each bar has a label and a value.
+	bars := []pterm.Bar{
+		{Label: "Bar 1", Value: 2},
+		{Label: "Bar 2", Value: -3},
+		{Label: "Bar 3", Value: -2},
+		{Label: "Bar 4", Value: 5},
+		{Label: "Longer Label", Value: 7},
 	}
 
+	// Print a section header.
+	// This is useful for separating different parts of the output.
 	pterm.DefaultSection.Println("Chart example with mixed values (note screen space usage in case when ABSOLUTE values of negative and positive parts are differ too much)")
-	_ = pterm.DefaultBarChart.WithBars(mixedBars).WithShowValue().Render()
-	_ = pterm.DefaultBarChart.WithHorizontal().WithBars(mixedBars).WithShowValue().Render()
+
+	// Create a bar chart with the defined bars.
+	// The chart will display the value of each bar.
+	// The Render() function is called to display the chart.
+	pterm.DefaultBarChart.WithBars(bars).WithShowValue().Render()
+
+	// Create a horizontal bar chart with the same bars.
+	// The chart will display the value of each bar.
+	// The Render() function is called to display the chart.
+	pterm.DefaultBarChart.WithHorizontal().WithBars(bars).WithShowValue().Render()
 }