From 845afc52e180e49cde37852f1703ce93e79d21be Mon Sep 17 00:00:00 2001 From: bashbunni Date: Thu, 16 May 2024 09:31:41 -0700 Subject: [PATCH] docs(godoc): include examples in godoc --- list/list.go | 53 ++++++++++++++++++++++++++++++++++++++++++---------- tree/tree.go | 45 +++++++++++++++++++++++++++++++++++++++----- 2 files changed, 83 insertions(+), 15 deletions(-) diff --git a/list/list.go b/list/list.go index c721d464..4ace6c35 100644 --- 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,7 +142,12 @@ 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) @@ -122,7 +155,7 @@ func (n *List) Enumerator(enum Enumerator) *List { 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 index 6009fd75..2ef2946f 100644 --- 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