feat: better docs for presets

lua/care/presets/init.lua

@@ -14,6 +14,7 @@ function Presets.Atom(entry, data)
     local components = require("care.presets.components")
     return {
         components.KindIcon(entry, "blended"),
+        { { " ", "@care.menu" } },
         components.Label(entry, data, true),
     }
 end

lua/care/types/preset_components.lua

@@ -2,12 +2,17 @@
 ---@class care.preset_components
 --- This adds a label for shortcuts [described here](/configuration_recipes#labels-and-shortcuts). By default this will
 --- use the `Comment` highlight group. This can be overridden though.
+--- ![image](https://github.com/user-attachments/assets/c476d4e4-9cee-4168-96a5-08a7492f08a8)
 ---@field ShortcutLabel fun(labels: string[], entry: care.entry, data: care.format_data, highlight_group?: string): { [1]: string, [2]: string }[]
 --- This components displays a kind icon. You can choose between the blended and foreground style.
+--- ![image](https://github.com/user-attachments/assets/aea84adf-578d-401d-bbbc-911198357a13)
+--- ![image](https://github.com/user-attachments/assets/9d4918e7-2f5b-491e-a21e-8213d705b8a0)
 ---@field KindIcon fun(entry: care.entry, style?: "blended"|"fg"): { [1]: string, [2]: string }[]
 --- This adds a completion item label to be displayed. Optionally this can also include a colored block if the items
 --- is a color and we know the value of the color.
+--- ![image](https://github.com/user-attachments/assets/28415670-8799-45fa-b175-cd1d643b2cd4)
 ---@field Label fun(entry: care.entry, data: care.format_data, display_colored_block?: boolean): { [1]: string, [2]: string }[]
 --- This component adds a colored block for the item if it is a color. The character used for the block can
 --- optionally be configured.
+--- ![image](https://github.com/user-attachments/assets/e6bf8620-92af-4ffa-8973-635cab7beec4)
 ---@field ColoredBlock fun(entry: care.entry, character?: string): { [1]: string, [2]: string }[]

lua/care/types/presets.lua

@@ -1,8 +1,14 @@
---- In this module some presets for the format_entry function are available.
+--- In this module some presets for the format_entry function are available. They can be accessed like this
+--- ```lua
+--- format_entry = function(entry, data)
+---     return require("care.presets").<preset_name>(entry, data)
+--- end
+--- ```
 ---@class care.presets
 --- The default preset. Just includes the label and a simple icon.
+--- ![image](https://github.com/user-attachments/assets/d3d7d338-db32-471f-ae20-89ea7703cb55)
 ---@field Default fun(entry: care.entry, data: care.format_data): { [1]: string, [2]: string }[][]
 --- The atom preset is an atom-like configuration. It displays the kind icon with a blended colored background and
---- the labelatom preset is an atom-like configuration. It displays the kind icon with a blended colored background
---- and the label.
+--- the label.
+--- ![image](https://github.com/user-attachments/assets/f8715fa7-1a0e-4be9-85ae-14b85cc2b7fd)
 ---@field Atom fun(entry: care.entry, data: care.format_data): { [1]: string, [2]: string }[][]

scripts/docs.lua

@@ -72,8 +72,17 @@ local docs_files = {
         title = "Internal Source",
     },
     { type_file = "lua/care/types/context.lua", doc_file = "docs/dev/context.md", title = "Context" },
-    { type_file = "lua/care/types/presets.lua", doc_file = "docs/presets.md", title = "Presets" },
-    { type_file = "lua/care/types/preset_utils.lua", doc_file = "docs/preset_utils.md", title = "Preset Utils" },
+    {
+        type_file = "lua/care/types/presets.lua",
+        doc_file = "docs/presets.md",
+        title = "Presets",
+        types = false,
+    },
+    {
+        type_file = "lua/care/types/preset_utils.lua",
+        doc_file = "docs/preset_utils.md",
+        title = "Preset Utils",
+    },
     {
         type_file = "lua/care/types/preset_components.lua",
         doc_file = "docs/preset_components.md",
@@ -128,7 +137,7 @@ local function cleanup_annotation(short_class_name, annotation)
     end
 end
 
-local function get_class_docs(path, title, desc, mark_optionals)
+local function get_class_docs(path, title, desc, mark_optionals, write_types)
     mark_optionals = mark_optionals or false
     local classes = read_classes(path)
     local contents = {
@@ -157,19 +166,23 @@ local function get_class_docs(path, title, desc, mark_optionals)
         else
             table.insert(contents, "## " .. gen_title(field.name))
         end
-        local annotation = cleanup_annotation(short_class_name, field.annotation)
-        table.insert(contents, "`" .. annotation .. "`")
-        local links = {}
-        for _, type_link in ipairs(link_list) do
-            if annotation:find(type_link[1]) then
-                table.insert(links, type_link[2])
+        if write_types then
+            local annotation = cleanup_annotation(short_class_name, field.annotation)
+            table.insert(contents, "`" .. annotation .. "`")
+            local links = {}
+            for _, type_link in ipairs(link_list) do
+                if annotation:find(type_link[1]) then
+                    table.insert(links, type_link[2])
+                end
+            end
+            if #links > 0 then
+                table.insert(contents, "")
+                table.insert(contents, "See " .. table.concat(links, ", "))
             end
-        end
-        if #links > 0 then
             table.insert(contents, "")
-            table.insert(contents, "See " .. table.concat(links, ", "))
+        else
+            table.insert(contents, "`" .. short_class_name .. "." .. field.name .. "`")
         end
-        table.insert(contents, "")
         table.insert(contents, table.concat(field.descriptions, "\n"))
     end
     for _, class in ipairs(classes) do
@@ -195,7 +208,7 @@ end
 
 local function write_class_docs()
     for _, docs in ipairs(docs_files) do
-        local contents = get_class_docs(docs.type_file, docs.title, docs.desc or nil)
+        local contents = get_class_docs(docs.type_file, docs.title, docs.desc or nil, docs.types or true)
         write_file(docs.doc_file, table.concat(contents, "\n"))
     end
 end