feat(fonts): updated font related type defs and doc comments + added missing doc for Wezterm.font_with_fallback

lua/wezterm/types/config.lua

@@ -269,8 +269,6 @@ local horiz_align = {
 ---
 ---@field width? "Cover"|"Contain"|number|string
 
----@alias AllFontAttributes Fonts|FontAttributes|FontFamilyAttributes
-
 ---@enum (key) FontRules.Blink
 local blink = {
   None = 1,
@@ -280,7 +278,7 @@ local blink = {
 
 ---@class FontRules
 ---@field blink? FontRules.Blink
----@field font? AllFontAttributes
+---@field font? TextStyle
 ---@field intensity? FormatItemAttribute.Intensity
 ---@field invisible? boolean
 ---@field italic? boolean
@@ -613,7 +611,7 @@ local exit_behavior_messaging = {
 --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback)
 --- - [`wezterm.font()`](lua://Wezterm.font)
 ---
----@field char_select_font? Fonts|FontFamilyAttributes
+---@field char_select_font? TextStyle
 ---Specifies the size of the font used with [`CharSelect`](https://wezterm.org/config/lua/keyassignment/CharSelect.html).
 ---
 ---@field char_select_font_size? number
@@ -713,7 +711,7 @@ local exit_behavior_messaging = {
 --- - [`wezterm.font()`](lua://Wezterm.font)
 --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback)
 ---
----@field command_palette_font? AllFontAttributes
+---@field command_palette_font? TextStyle
 ---Specifies the size of the font used with `ActivateCommandPalette`.
 ---
 ---See:
@@ -1108,7 +1106,7 @@ local exit_behavior_messaging = {
 --- - [`wezterm.font()`](lua://Wezterm.font)
 --- - [`wezterm.font_with_fallback()`](lua://Wezterm.font_with_fallback)
 ---
----@field font? AllFontAttributes
+---@field font? TextStyle
 ---@field font_colr_rasterizer? FontRasterizer
 ---By default, wezterm will use an appropriate system-specific method
 ---for locating the fonts that you specify using the options below.
@@ -1818,7 +1816,7 @@ local exit_behavior_messaging = {
 ---config.pane_select_font = wezterm.font 'Roboto'
 ---```
 ---
----@field pane_select_font? AllFontAttributes
+---@field pane_select_font? TextStyle
 ---@field pane_select_font_size? number
 ---If non-zero, specifies the period (in seconds) at which various statistics are logged.
 ---

lua/wezterm/types/wezterm.lua

@@ -456,6 +456,13 @@ local font_stretch = {
   UltraExpanded = 1,
 }
 
+---@enum (key) FontStyle
+local font_style = {
+  Italic = 1,
+  Normal = 1,
+  Oblique = 1,
+}
+
 ---@enum (key) FreeTypeLoadFlags
 local freetype_load_flags = {
   DEFAUlT = 1,
@@ -466,18 +473,6 @@ local freetype_load_flags = {
   NO_HINTING = 1,
 }
 
----@class FontAttributes
----@field is_fallback? boolean
----@field is_synthetic? boolean
----@field scale? number
----@field stretch? FontStretch
----Whether the font should be an italic variant.
----
----@field style? "Normal"|"Italic"|"Oblique"
----Whether the font should be a bold variant.
----
----@field weight? FontWeight
-
 ---@enum (key) FreeTypeTarget
 local freetype_target = {
   HorizontalLcd = 1,
@@ -487,10 +482,10 @@ local freetype_target = {
   VerticalLcd = 1,
 }
 
----`FontAttributes`-like class but with font family
----and other extensions included.
+---@class FontAttributesBase
+---To control whether a font is considered to have emoji (rather than text)
+---presentation glyphs for emoji.
 ---
----@class FontFamilyAttributes: FontAttributes
 ---@field assume_emoji_presentation? boolean
 ---@field family string
 ---you can combine the flags like `"NO_HINTING|MONOCHROME"`
@@ -511,9 +506,47 @@ local freetype_target = {
 --- - [`config.font_shaper`](lua://Config.font_shaper)
 ---
 ---@field harfbuzz_features? HarfbuzzFeatures[]
+---@field scale? number
+---@field stretch? FontStretch
+---This option will only be respected if the `italic` option is `nil`.
+---
+---@field style? FontStyle
+---@field weight? FontWeight
+
+---Argument type for `Wezterm.font()` and `Wezterm.font_with_fallback()`.
+---@class FontFamilyAttributes: FontAttributesBase
+---Setting this option to `true`, will overwrite the `style` option to `Italic`.
+---Setting this option to `false` will overwrite the `style` option to `Normal`.
+---
+---@field italic? boolean
+
+---Corresponds to the internal `FontAttributes` struct that is used to
+---select a single named font.
+---
+---@class FontAttributes: FontAttributesBase
+---@field is_fallback? boolean
+---@field is_synthetic? boolean
+
+---@class TextStyleAttributes
+---@field bold? boolean
+---If set, when rendering text that is set to the default
+---foreground color, use this color instead.  This is most
+---useful in a `Config.font_rules` section to implement changing
+---the text color for eg: bold text.
+---
+---For more information and examples, see:
+--- - [Font Rules](ttps://wezterm.org/config/lua/config/font_rules.html)
+--- - [`config.font_rules`](lua://Config.font_rules)
+---
+---@field foreground? string
+---@field italic? boolean
+---@field stretch? FontStretch
+---@field style? FontStyle
+---@field weight? FontWeight
 
----@class Fonts
+---@class TextStyle
 ---@field fonts FontAttributes[]
+---@field foreground? string
 
 ---@class WindowFrameConfig
 ---@field active_titlebar_bg? string
@@ -531,7 +564,7 @@ local freetype_target = {
 ---@field button_fg? string
 ---@field button_hover_bg? string
 ---@field button_hover_fg? string
----@field font? AllFontAttributes
+---@field font? TextStyle
 ---@field font_size? number
 ---@field inactive_titlebar_bg? string
 ---@field inactive_titlebar_border_bottom? string
@@ -1221,7 +1254,7 @@ function M.emit(event, ...) end
 function M.enumerate_ssh_hosts(ssh_config_file_name) end
 
 ---This function constructs a Lua table that corresponds to the internal
----`FontFamilyAttributes` struct that is used to select a single named font:
+---`FontAttributes` struct that is used to select a single named font:
 ---
 ---```lua
 ---local wezterm = require 'wezterm'
@@ -1242,24 +1275,32 @@ function M.enumerate_ssh_hosts(ssh_config_file_name) end
 --- - The postscript name, which is an ostensibly unique name identifying a given font and style
 ---   that is encoded into the font by the font designer.
 ---
----See also:
---- - [`FontAttributes`](lua://FontAttributes)
---- - [`FontFamilyAttributes`](lua://FontFamilyAttributes)
+---When specifying a font using its family name, the second `attributes` parameter is
+---an **optional** table that can be used to specify style attributes.
+---
+---See:
+--- - [`TextStyleAttributes`](lua://TextStyleAttributes)
+--- - [`TextStyle`](lua://TextStyle)
 ---
----@param name string
----@param attributes? FontAttributes
----@return Fonts|FontFamilyAttributes
-function M.font(name, attributes) end
+---@param font string|FontFamilyAttributes
+---@param attributes? TextStyleAttributes
+---@return TextStyle
+function M.font(font, attributes) end
 
 ---This function constructs a Lua table that corresponds to the internal
----`FontFamilyAttributes` struct that is used to select a single named font.
+---`FontAttributes` struct that is used to select a single named font.
 ---
----When specifying a font using its family name, the second attributes parameter is
----an **optional** table that can be used to specify style attributes.
+---The first parameter is a table where the font family and the attributes are combined.
 ---
----You can use the expanded form mentioned above to override freetype and harfbuzz settings
+---You can use this expanded table form to override freetype and harfbuzz settings
 ---just for the specified font.
 ---
+---The second attributes parameter is an **optional** table that can also be used
+---to specify style attributes.
+---
+---**Note**, that the attributes specified in the second `attributes` parameter will take precedence over
+---any attributes specified in the first `font` parameter.
+---
 ---This example shows how to disable the default ligature feature just for this particular font:
 ---
 ---```lua
@@ -1272,30 +1313,54 @@ function M.font(name, attributes) end
 ---}
 ---```
 ---
----The following options can be specified in the same way:
---- - [`harfbuzz_features`](lua://FontFamilyAttributes.harfbuzz_features)
---- - [`freetype_load_target`](lua://FontFamilyAttributes.freetype_load_target)
---- - [`freetype_render_target`](lua://FontFamilyAttributes.freetype_render_target)
---- - [`freetype_load_flags`](lua://FontFamilyAttributes.freetype_load_flags)
---- - [`assume_emoji_presentation`](lua://FontFamilyAttributes.assume_emoji_presentation)
----   to control whether a font is considered to have emoji (rather than text) presentation glyphs
----   for emoji
----
---- See:
----  - [`FontFamilyAttributes`](lua://FontFamilyAttributes)
+---See:
+--- - [`FontFamilyAttributes`](lua://FontFamilyAttributes)
+--- - [`TextStyleAttributes`](lua://TextStyleAttributes)
+--- - [`TextStyle`](lua://TextStyle)
 ---
----@param attributes FontFamilyAttributes
----@return Fonts|FontFamilyAttributes fonts
-function M.font(attributes) end
+---@param font FontFamilyAttributes
+---@param attributes? TextStyleAttributes
+---@return TextStyle
+function M.font(font, attributes) end
 
----TODO: Complete description.
+---This function constructs a lua table that configures a font with fallback processing.
+---Glyphs are looked up in the first font in the list but if missing the next font is checked and so on.
 ---
----Here's some [info](https://wezterm.org/config/lua/wezterm/font_with_fallback.html) on this
----function.
+---The first parameter is a table listing the fonts in their preferred order.
+---The fonts can be specified by the their family or using the alternative form where the family and attributes
+---are specified as part of the same lua table:
+---
+---```lua
+---local wezterm = require 'wezterm'
+---return {
+---  font = wezterm.font_with_fallback {
+---  {
+---    family = 'JetBrains Mono'
+---    harfbuzz_features = { 'calt=0', 'clig=0', 'liga=0' },
+---    weight = 'Medium'
+---  },
+---  { family = 'Terminus', weight = 'Bold' },
+---  'Noto Color Emoji',
+---}
+---```
+---
+---WezTerm implicitly adds its default fallback to the list that you specify.
+---
+---The second `attributes` parameter is an **optional** table that can also be used
+---to specify style attributes.
+---
+---**Note**, that the attributes specified in the second `attributes` parameter will take precedence over
+---any attributes specified in the individual font tables and will affect all listed fonts.
+---
+---See:
+--- - [`FontFamilyAttributes`](lua://FontFamilyAttributes)
+--- - [`TextStyleAttributes`](lua://TextStyleAttributes)
+--- - [`TextStyle`](lua://TextStyle)
 ---
----@param fonts (string|FontAttributes)[]
----@return Fonts fallback_fonts
-function M.font_with_fallback(fonts) end
+---@param fonts (string|FontFamilyAttributes)[]
+---@param attributes? TextStyleAttributes
+---@return TextStyle
+function M.font_with_fallback(fonts, attributes) end
 
 ---Can be used to produce a formatted string with terminal graphic attributes
 ---such as `bold`, `italic` and `colors`.