docs: do some slight fix and rewrite for comp docs

.hilbishrc.lua

@@ -47,16 +47,3 @@ end)
 bait.catch('hilbish.notification', function(notif)
 	doNotifyPrompt()
 end)
-
-hilbish.complete('command.comp', function(query, ctx, fields)
-	local cg = {
-	items = {
-			'list item 1',
-			['--command-flag-here'] = {'this does a thing', '--the-flag-alias'},
-			['--styled-command-flag-here'] = {'this does a thing', '--the-flag-alias', display = lunacolors.blue '--styled-command-flag-here'}
-		},
-		type = 'list'
-	}
-
-	return {cg}, prefix
-end)

CHANGELOG.md

@@ -4,6 +4,18 @@
 ### Added
 - Forward/Right arrow key will fill in hint text (#327)
 - Values returned by bait hooks will be passed to the `throw` caller
+- `display` property to completion groups entries to style completion entries when type is `list`.
+example:
+```lua
+local cg = {
+	items = {
+		'list item 1',
+		['--command-flag-here'] = {'this does a thing', '--the-flag-alias'},
+		['--styled-command-flag-here'] = {'this does a thing', '--the-flag-alias', display = lunacolors.blue '--styled-command-flag-here'}
+	},
+	type = 'list'
+}
+```
 
 ## [2.3.4] - 2024-12-28
 ### Fixed

docs/completions.md

@@ -56,6 +56,50 @@ return {cg, cg2}, prefix
 Which looks like this:  
 {{< video src="https://safe.saya.moe/t4CiLK6dgPbD.mp4" >}}
 
+# Completion Group Types
+### grid
+Grid is the simplest completion group type. All items are strings and when
+completion is done is displayed in a grid based on size.
+
+Example:
+```lua
+{
+	items = {'just', 'a bunch', 'of items', 'here', 'hehe'},
+	type = 'grid'
+}
+```
+
+### list
+The list completion group type displays in a list. A list item can either be a string, or a table for additional display options.
+A completion alias can be specified either as the `2nd` entry in the options table
+or te `alias` key.
+
+A description can optionally be displayed for a list item, which is either the `1st`
+entry or the `description` key.
+
+Lastly, list entries can be styled. This is done with the `display` key. If this is present, this
+overrides what the completion item *looks* like.
+
+Example:
+```lua
+{
+	items = {
+		['--flag'] = {
+			description = 'this flag nukes the bri ish',
+			alias = '--bye-bri-ish',
+			display = lunacolors.format('--{blue}fl{red}ag')
+		},
+		['--flag2'] = {
+			'make pizza', -- description
+			'--pizzuh', -- alias
+			display = lunacolors.yellow '--pizzuh'
+		},
+		'--flag3'
+	},
+	type = 'list'
+}
+```
+
 # Completion Handler
 Like most parts of Hilbish, it's made to be extensible and
 customizable. The default handler for completions in general can