From 15e05aaf038eecff5bdf38cdb61455519dbf57d7 Mon Sep 17 00:00:00 2001
From: Takase <20792268+takase1121@users.noreply.github.com>
Date: Sat, 26 Aug 2023 23:32:39 +0800
Subject: [PATCH] docs(core.config): add documentation for config options
 (#1512)

* docs(core.config): add documentation for config options

* docs(core.config): remove wrong newline

* docs(core.config): remove trailing whitespace

* docs(core.config): add missing whitespace

* docs(core.config): add disclaimer for core.file_size_limit

* docs(core.config): fix wrong description of the pattern

* docs(core.config): fix wrong description

* docs(core.config): fix wrong description for transitions

* docs(core.config): guide user to drawwhitespace plugin

* docs(core.config): clarify libdecor usage

* docs(core.config): clarify various things

* docs(core.config): clarify more about libdecor support

* docs(core.config): fix missing enum separator

* docs(core.config): remove wayland-specific advice on config.borderless
---
 data/core/config.lua | 206 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 202 insertions(+), 4 deletions(-)

diff --git a/data/core/config.lua b/data/core/config.lua
index c1a16b11..2381639f 100644
--- a/data/core/config.lua
+++ b/data/core/config.lua
@@ -2,15 +2,71 @@ local common = require "core.common"
 
 local config = {}
 
+---The frame rate of Lite XL.
+---Note that setting this value to the screen's refresh rate
+---does not eliminate screen tearing.
+---
+---Defaults to 60.
+---@type number
 config.fps = 60
+
+---Maximum number of log items that will be stored.
+---When the number of log items exceed this value, old items will be discarded.
+---
+---Defaults to 800.
+---@type number
 config.max_log_items = 800
+
+---The timeout, in seconds, before a message dissapears from StatusView.
+---
+---Defaults to 5.
+---@type number
 config.message_timeout = 5
+
+---The number of pixels scrolled per-step.
+---
+---Defaults to 50 * SCALE.
+---@type number
 config.mouse_wheel_scroll = 50 * SCALE
+
+---Enables/disables transitions when scrolling with the scrollbar.
+---When enabled, the scrollbar will have inertia and slowly move towards the cursor.
+---Otherwise, the scrollbar will immediately follow the cursor.
+---
+---Defaults to false.
+---@type boolean
 config.animate_drag_scroll = false
+
+---Enables/disables scrolling past the end of a document.
+---
+---Defaults to true.
+---@type boolean
 config.scroll_past_end = true
----@type "expanded" | "contracted" | false @Force the scrollbar status of the DocView
+
+---@alias config.scrollbartype
+---| "expanded" # A thicker scrollbar is shown at all times.
+---| "contracted" # A thinner scrollbar is shown at all times.
+---| false # The scrollbar expands when the cursor hovers over it.
+
+---Controls whether the DocView scrollbar is always shown or hidden.
+---This option does not affect other View's scrollbars.
+---
+---Defaults to false.
+---@type config.scrollbartype
 config.force_scrollbar_status = false
+
+---The file size limit, in megabytes.
+---Files larger than this size will not be shown in the file picker.
+---
+---Defaults to 10.
+---@type number
 config.file_size_limit = 10
+
+---A list of files and directories to ignore.
+---Each element is a Lua pattern, where patterns ending with a forward slash
+---are recognized as directories while patterns ending with an anchor ("$") are
+---recognized as files.
+---@type string[]
 config.ignore_files = {
   -- folders
   "^%.svn/",        "^%.git/",   "^%.hg/",        "^CVS/", "^%.Trash/", "^%.Trash%-.*/",
@@ -21,46 +77,188 @@ config.ignore_files = {
   "%.suo$",         "%.pdb$",       "%.idb$",        "%.class$", "%.psd$", "%.db$",
   "^desktop%.ini$", "^%.DS_Store$", "^%.directory$",
 }
+
+---Lua pattern used to find symbols when advanced syntax highlighting
+---is not available.
+---This pattern is also used for navigation, e.g. move to next word.
+---
+---The default pattern matches all letters, followed by any number
+---of letters and digits.
+---@type string
 config.symbol_pattern = "[%a_][%w_]*"
+
+---A list of characters that delimits a word.
+---
+---The default is ``" \t\n/\\()\"':,.;<>~!@#$%^&*|+=[]{}`?-"``
+---@type string
 config.non_word_chars = " \t\n/\\()\"':,.;<>~!@#$%^&*|+=[]{}`?-"
+
+---The timeout, in seconds, before several consecutive actions
+---are merged as a single undo step.
+---
+---The default is 0.3 seconds.
+---@type number
 config.undo_merge_timeout = 0.3
+
+---The maximum number of undo steps per-document.
+---
+---The default is 10000.
+---@type number
 config.max_undos = 10000
+
+---The maximum number of tabs shown at a time.
+---
+---The default is 8.
+---@type number
 config.max_tabs = 8
+
+---Shows/hides the tab bar when there is only one tab open.
+---
+---The tab bar is always shown by default.
+---@type boolean
 config.always_show_tabs = true
--- Possible values: false, true, "no_selection"
+
+---@alias config.highlightlinetype
+---| true # Always highlight the current line.
+---| false # Never highlight the current line.
+---| "no_selection" # Highlight the current line if no text is selected.
+
+---Highlights the current line.
+---
+---The default is true.
+---@type config.highlightlinetype
 config.highlight_current_line = true
+
+---The spacing between each line of text.
+---
+---The default is 120% of the height of the text (1.2).
+---@type number
 config.line_height = 1.2
+
+---The number of spaces each level of indentation represents.
+---
+---The default is 2.
+---@type number
 config.indent_size = 2
+
+---The type of indentation.
+---
+---The default is "soft" (spaces).
+---@type "soft" | "hard"
 config.tab_type = "soft"
+
+---Do not remove whitespaces when advancing to the next line.
+---
+---Defaults to false.
+---@type boolean
 config.keep_newline_whitespace = false
+
+---Maximum number of characters per-line for the line guide.
+---
+---Defaults to 80.
+---@type number
 config.line_limit = 80
+
+---Maximum number of project files to keep track of.
+---If the number of files in the project exceeds this number,
+---Lite XL will not be able to keep track of them.
+---They will be not be searched when searching for files or text.
+---
+---Defaults to 2000.
+---@type number
 config.max_project_files = 2000
+
+---Enables/disables all transitions.
+---
+---Defaults to true.
+---@type boolean
 config.transitions = true
+
+---Enable/disable individual transitions.
+---These values are overriden by `config.transitions`.
 config.disabled_transitions = {
+  ---Disables scrolling transitions.
   scroll = false,
+  ---Disables transitions for CommandView's suggestions list.
   commandview = false,
+  ---Disables transitions for showing/hiding the context menu.
   contextmenu = false,
+  ---Disables transitions when clicking on log items in LogView.
   logview = false,
+  ---Disables transitions for showing/hiding the Nagbar.
   nagbar = false,
+  ---Disables transitions when scrolling the tab bar.
   tabs = false,
+  ---Disables transitions when a tab is being dragged.
   tab_drag = false,
+  ---Disables transitions when a notification is shown.
   statusbar = false,
 }
+
+---The rate of all transitions.
+---
+---Defaults to 1.
+---@type number
 config.animation_rate = 1.0
+
+---The caret's blinking period, in seconds.
+---
+---Defaults to 0.8.
+---@type number
 config.blink_period = 0.8
+
+---Disables caret blinking.
+---
+---Defaults to false.
+---@type boolean
 config.disable_blink = false
+
+---Draws whitespaces as dots.
+---This option is deprecated.
+---Please use the drawwhitespace plugin instead.
+---@deprecated
 config.draw_whitespace = false
+
+---Disables system-drawn window borders.
+---
+---When set to true, Lite XL draws its own window decorations,
+---which can be useful for certain setups.
+---
+---Defaults to false.
+---@type boolean
 config.borderless = false
+
+---Shows/hides the close buttons on tabs.
+---When hidden, users can close tabs via keyboard shortcuts or commands.
+---
+---Defaults to true.
+---@type boolean
 config.tab_close_button = true
+
+---Maximum number of clicks recognized by Lite XL.
+---
+---Defaults to 3.
+---@type number
 config.max_clicks = 3
 
--- set as true to be able to test non supported plugins
+---Disables plugin version checking.
+---Do not change this unless you know what you are doing.
+---
+---Defaults to false.
+---@type boolean
 config.skip_plugins_version = false
 
 -- holds the plugins real config table
 local plugins_config = {}
 
--- virtual representation of plugins config table
+---A table containing configuration for all the plugins.
+---
+---This is a metatable that automaticaly creates a minimal
+---configuration when a plugin is initially configured.
+---Each plugins will then call `common.merge()` to get the finalized
+---plugin config.
+---Do not use raw operations on this table.
+---@type table
 config.plugins = {}
 
 -- allows virtual access to the plugins config table