docs(godoc): include examples in godoc

charmbracelet · May 16, 2024 · 845afc5 · 845afc5
1 parent d9dfac2
commit 845afc5
Show file tree

Hide file tree

Showing 2 changed files with 83 additions and 15 deletions.
diff --git a/list/list.go b/list/list.go
@@ -15,7 +15,8 @@
 //	fmt.Println(l)
 //
 // The list package provides built-in enumerator styles to help glamourize your
-// lists. Lists are fully customizable, so let your creativity flow.
+// lists. This package wraps the tree package with list-specific styling. Lists
+// are fully customizable, so let your creativity flow.
 package list
 
 import (
@@ -46,7 +47,7 @@ func (n *List) Hidden() bool {
 }
 
 // Hide sets whether or not to hide the tree.
-// This is useful for collapsing / hiding sub-tree.
+// This is useful for collapsing or hiding sub-lists.
 func (n *List) Hide(hide bool) *List {
 	n.inner.Hide(hide)
 	return n
@@ -71,33 +72,60 @@ func (n *List) String() string {
 	return n.inner.String()
 }
 
-// EnumeratorStyle implements Renderer.
-// Margins and paddings should usually be set only in ItemStyle/ItemStyleFunc.
+// EnumeratorStyle sets the enumeration style.
+// Margins and paddings should usually be set only in ItemStyle or ItemStyleFunc.
 func (n *List) EnumeratorStyle(style lipgloss.Style) *List {
 	n.inner.EnumeratorStyle(style)
 	return n
 }
 
-// EnumeratorStyleFunc implements Renderer.
+// EnumeratorStyleFunc sets the enumeration style function. Use this function
+// for conditional styling.
+//
 // Margins and paddings should usually be set only in ItemStyle/ItemStyleFunc.
+//
+//	l := list.New().
+//		EnumeratorStyleFunc(func(_ tree.Data, i int) lipgloss.Style {
+//		    if i == 1 {
+//		        return lipgloss.NewStyle().Foreground(hightlightColor)
+//		    }
+//		    return lipgloss.NewStyle().Foreground(dimColor)
+//		})
 func (n *List) EnumeratorStyleFunc(fn StyleFunc) *List {
 	n.inner.EnumeratorStyleFunc(tree.StyleFunc(fn))
 	return n
 }
 
-// ItemStyle implements Renderer.
+// ItemStyle sets the item style.
+//
+//	l := tree.New("Duck", "Duck", "Duck", "Goose", "Duck").
+//		ItemStyle(lipgloss.NewStyle().Foreground(lipgloss.Color(255)))
 func (n *List) ItemStyle(style lipgloss.Style) *List {
 	n.inner.ItemStyle(style)
 	return n
 }
 
-// ItemStyleFunc implements Renderer.
+// ItemStyleFunc sets the item style function. Use this for conditional styling.
+// For example:
+//
+//	l := list.New().
+//		ItemStyleFunc(func(_ tree.Data, i int) lipgloss.Style {
+//			st := baseStyle.Copy()
+//			if selectedIndex == i {
+//				return st.Foreground(hightlightColor)
+//			}
+//			return st.Foreground(dimColor)
+//		})
 func (n *List) ItemStyleFunc(fn StyleFunc) *List {
 	n.inner.ItemStyleFunc(tree.StyleFunc(fn))
 	return n
 }
 
-// Item appends an item to a list.
+// Item appends an item to a list. Lists support nesting.
+//
+//	l := list.New().
+//	Item("Item 1").
+//	Item(list.New("Item 1.1", "Item 1.2"))
 func (n *List) Item(item any) *List {
 	switch item := item.(type) {
 	case *List:
@@ -114,15 +142,20 @@ func (n *List) Items(items ...any) *List {
 	return n
 }
 
-// Enumerator implements Renderer.
+// Enumerator sets the enumerator implementation. Lipgloss includes
+// predefined enumerators including bullets, roman numerals, and more. For
+// example, you can have a numbered list:
+//
+//	list.New().
+//		Enumerator(Arabic)
 func (n *List) Enumerator(enum Enumerator) *List {
 	n.inner.Enumerator(func(data tree.Data, i int) (string, string) {
 		return " ", enum(data, i)
 	})
 	return n
 }
 
-// New returns a new list.
+// New returns a new list with a bullet enumerator.
 func New(items ...any) *List {
 	l := &List{
 		inner: tree.New().Items(items...),

diff --git a/tree/tree.go b/tree/tree.go
@@ -72,7 +72,7 @@ func (n *Tree) Hidden() bool {
 }
 
 // Hide sets whether or not to hide the tree.
-// This is useful for collapsing / hiding sub-tree.
+// This is useful for collapsing or hiding sub-trees.
 func (n *Tree) Hide(hide bool) *Tree {
 	n.hide = hide
 	return n
@@ -155,6 +155,10 @@ func (n *Tree) Item(item any) *Tree {
 }
 
 // Items add multiple items to the tree.
+//
+//	t := tree.New().
+//		Root("Nyx").
+//		Items("Qux", "Quux").
 func (n *Tree) Items(items ...any) *Tree {
 	for _, item := range items {
 		n.Item(item)
@@ -198,14 +202,27 @@ func (n *Tree) ensureRenderer() *defaultRenderer {
 }
 
 // EnumeratorStyle sets the enumeration style.
-// Margins and paddings should usually be set only in ItemStyle/ItemStyleFunc.
+// Margins and paddings should usually be set only in ItemStyle or ItemStyleFunc.
+//
+//	t := tree.New("Duck", "Duck", "Duck", "Goose", "Duck").
+//		EnumeratorStyle(lipgloss.NewStyle().Foreground(lipgloss.Color("#00d787")))
 func (n *Tree) EnumeratorStyle(style lipgloss.Style) *Tree {
 	n.ensureRenderer().style.enumeratorFunc = func(Data, int) lipgloss.Style { return style }
 	return n
 }
 
-// EnumeratorStyleFunc sets the enumeration style function.
+// EnumeratorStyleFunc sets the enumeration style function. Use this function
+// for conditional styling.
+//
 // Margins and paddings should usually be set only in ItemStyle/ItemStyleFunc.
+//
+//	t := tree.New().
+//		EnumeratorStyleFunc(func(_ tree.Data, i int) lipgloss.Style {
+//		    if i == 1 {
+//		        return lipgloss.NewStyle().Foreground(hightlightColor)
+//		    }
+//		    return lipgloss.NewStyle().Foreground(dimColor)
+//		})
 func (n *Tree) EnumeratorStyleFunc(fn StyleFunc) *Tree {
 	if fn == nil {
 		fn = func(Data, int) lipgloss.Style { return lipgloss.NewStyle() }
@@ -215,12 +232,25 @@ func (n *Tree) EnumeratorStyleFunc(fn StyleFunc) *Tree {
 }
 
 // ItemStyle sets the item style.
+//
+//	t := tree.New("Duck", "Duck", "Duck", "Goose", "Duck").
+//		ItemStyle(lipgloss.NewStyle().Foreground(lipgloss.Color(255)))
 func (n *Tree) ItemStyle(style lipgloss.Style) *Tree {
 	n.ensureRenderer().style.itemFunc = func(Data, int) lipgloss.Style { return style }
 	return n
 }
 
-// ItemStyleFunc sets the item style function.
+// ItemStyleFunc sets the item style function. Use this for conditional styling.
+// For example:
+//
+//	t := tree.New().
+//		ItemStyleFunc(func(_ tree.Data, i int) lipgloss.Style {
+//			st := baseStyle.Copy()
+//			if selectedIndex == i {
+//				return st.Foreground(hightlightColor)
+//			}
+//			return st.Foreground(dimColor)
+//		})
 func (n *Tree) ItemStyleFunc(fn StyleFunc) *Tree {
 	if fn == nil {
 		fn = func(Data, int) lipgloss.Style { return lipgloss.NewStyle() }
@@ -229,7 +259,12 @@ func (n *Tree) ItemStyleFunc(fn StyleFunc) *Tree {
 	return n
 }
 
-// Enumerator sets the enumerator implementation.
+// Enumerator sets the enumerator implementation. Lipgloss includes
+// predefined enumerators including bullets, roman numerals, and more. For
+// example, you can have a numbered list:
+//
+//	tree.New().
+//		Enumerator(Arabic)
 func (n *Tree) Enumerator(enum Enumerator) *Tree {
 	n.ensureRenderer().enumerator = enum
 	return n