From badae2ba9dcc9f2ad76c5717dac5464eaa6b089f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E9=80=9A=E6=B4=B2?= Date: Sun, 3 Aug 2025 10:16:46 +0800 Subject: [PATCH] JsonSchema: Improves JSON schema enums with oneOf objects containing descriptive explanations for allowed values --- doc/json_schema.json | 361 +++++++++++++++++++++++++++++++++---------- 1 file changed, 276 insertions(+), 85 deletions(-) diff --git a/doc/json_schema.json b/doc/json_schema.json index d7baa0735..b8fce5a35 100644 --- a/doc/json_schema.json +++ b/doc/json_schema.json @@ -559,23 +559,67 @@ "properties": { "type": { "description": "Set the type of the logo", - "enum": [ - "auto", - "builtin", - "small", - "file", - "file-raw", - "data", - "data-raw", - "command-raw", - "sixel", - "kitty", - "kitty-direct", - "kitty-icat", - "iterm", - "chafa", - "raw", - "none" + "oneOf": [ + { + "const": "auto", + "description": "If something is given, first try built-in, then file. Otherwise detect logo" + }, + { + "const": "builtin", + "description": "Built-in ASCII art" + }, + { + "const": "small", + "description": "Built-in ASCII art, small version (not all logos support this option)" + }, + { + "const": "file", + "description": "Text file, printed with color code replacement" + }, + { + "const": "file-raw", + "description": "Text file, printed as is" + }, + { + "const": "data", + "description": "Text data, printed with color code replacement" + }, + { + "const": "data-raw", + "description": "Text data, printed as is" + }, + { + "const": "sixel", + "description": "Image file, printed as sixel codes" + }, + { + "const": "kitty", + "description": "Image file, printed using kitty graphics protocol" + }, + { + "const": "kitty-direct", + "description": "Image file, tells the terminal emulator to read image data from the specified file" + }, + { + "const": "kitty-icat", + "description": "Image file, uses `kitten icat` to display the image. Requires binary `kitten` to be installed" + }, + { + "const": "iterm", + "description": "Image file, uses `iTerm` image protocol" + }, + { + "const": "chafa", + "description": "Image file, prints `ASCII` art image generated by `libchafa`" + }, + { + "const": "raw", + "description": "Image file, printed as `raw` binary string image" + }, + { + "const": "none", + "description": "Disable logo printing" + } ], "default": "auto" }, @@ -700,32 +744,71 @@ "canvasMode": { "type": "string", "description": "Determine how colors are used in the output. This value maps to enum ChafaCanvasMode.", - "enum": [ - "TRUECOLOR", - "INDEXED_256", - "INDEXED_240", - "INDEXED_16", - "FGBG_BGFG", - "FGBG", - "INDEXED_8", - "INDEXED_16_8" + "oneOf": [ + { + "const": "TRUECOLOR", + "description": "Use 24-bit true colors" + }, + { + "const": "INDEXED_256", + "description": "Use 256 colors" + }, + { + "const": "INDEXED_240", + "description": "Use 240 colors, but avoid using the lower 16 whose values vary between terminal environments" + }, + { + "const": "INDEXED_16", + "description": "Use 16 colors using the aixterm ANSI extension" + }, + { + "const": "FGBG_BGFG", + "description": "Use default foreground and background colors, plus inversion" + }, + { + "const": "FGBG", + "description": "Use default foreground and background colors. No ANSI codes will be used" + }, + { + "const": "INDEXED_8", + "description": "Use 8 colors, compatible with original ANSI X3.64" + }, + { + "const": "INDEXED_16_8", + "description": "Use 16 FG colors (8 of which enabled with bold/bright) and 8 BG colors" + } ] }, "colorSpace": { "type": "string", "description": "Set color space used for quantization. This value maps to enum ChafaColorSpace.", - "enum": [ - "RGB", - "DIN99D" + "oneOf": [ + { + "const": "RGB", + "description": "RGB color space. Fast but imprecise" + }, + { + "const": "DIN99D", + "description": "DIN99d color space. Slower, but good perceptual color precision" + } ] }, "ditherMode": { "type": "string", "description": "Set output dither mode (No effect with 24-bit color). This value maps to enum ChafaDitherMode.", - "enum": [ - "NONE", - "ORDERED", - "DIFFUSION" + "oneOf": [ + { + "const": "NONE", + "description": "No dithering" + }, + { + "const": "ORDERED", + "description": "Ordered dithering (Bayer or similar)" + }, + { + "const": "DIFFUSION", + "description": "Error diffusion dithering (Floyd-Steinberg or similar)" + } ] } } @@ -889,11 +972,23 @@ "type": { "type": "string", "description": "Set whether to show icon before string keys", - "enum": [ - "none", - "string", - "icon", - "both" + "oneOf": [ + { + "const": "none", + "description": "Disable keys" + }, + { + "const": "string", + "description": "Show string keys" + }, + { + "const": "icon", + "description": "Show icon keys (requires newest nerd font)" + }, + { + "const": "both", + "description": "Show both icon and string keys" + } ], "default": "string" }, @@ -955,7 +1050,24 @@ "unit": { "type": "string", "description": "Set the unit of temperature", - "enum": ["D", "Default", "Celsius", "C", "Fahrenheit", "F", "Kelvin", "K"], + "oneOf": [ + { + "const": "C", + "description": "Celsius" + }, + { + "const": "F", + "description": "Fahrenheit" + }, + { + "const": "K", + "description": "Kelvin" + }, + { + "const": "D", + "description": "Default (alias for Celsius)" + } + ], "default": "D" }, "ndigits": { @@ -1821,14 +1933,35 @@ "symbol": { "description": "Set the symbol to use", "type": "string", - "enum": [ - "block", - "background", - "circle", - "diamond", - "triangle", - "square", - "star" + "oneOf": [ + { + "const": "block", + "description": "\u2588\u2588\u2588" + }, + { + "const": "background", + "description": "(whitespaces with background)" + }, + { + "const": "circle", + "description": "\u25cf" + }, + { + "const": "diamond", + "description": "\u25c6" + }, + { + "const": "triangle", + "description": "\u25b2" + }, + { + "const": "square", + "description": "\u25a0" + }, + { + "const": "star", + "description": "\u2605" + } ], "default": "background" }, @@ -1887,7 +2020,7 @@ "type": "string" }, "param": { - "description": "Set the parameter used when starting the shell\nDefault: /c for Windows, -c for *nix", + "description": "Set the parameter used when starting the shell\nIf set to an empty string, it will be ignored\nDefault: /c for Windows, -c for *nix", "type": "string" }, "text": { @@ -2251,8 +2384,8 @@ }, "slowVersionDetection": { "type": "boolean", - "description": "Set if DE version should be detected with slow operations.\nShould be unnecessary for most cases.", - "default": "false" + "description": "Set if DE version should be detected with slow operations.\nShould be unnecessary for most cases.\nThis is only used as a fallback method. Please file a bug report if you encounter any issues.", + "default": false }, "key": { "$ref": "#/$defs/key" @@ -2287,10 +2420,19 @@ "description": "Print DNS servers" }, "showType": { - "enum": [ - "ipv4", - "ipv6", - "both" + "oneOf": [ + { + "const": "ipv4", + "description": "Show IPv4 addresses only" + }, + { + "const": "ipv6", + "description": "Show IPv6 addresses only" + }, + { + "const": "both", + "description": "Show both IPv4 and IPv6 addresses" + } ], "default": "both", "description": "Specify the type of DNS servers should be detected" @@ -2436,31 +2578,62 @@ "$ref": "#/$defs/temperature" }, "driverSpecific": { - "description": "Use driver specific method to detect more detailed GPU information (memory usage, core count, etc)", + "description": "Use driver specific method to detect more detailed GPU information (memory usage, core count, etc)\nRequires the latest GPU drivers to be installed.", "type": "boolean", "default": false }, "detectionMethod": { "description": "Force using a specified method to detect GPUs", "type": "string", - "enum": [ - "auto", - "pci", - "vulkan", - "opencl", - "opengl" + "oneOf": [ + { + "const": "auto", + "description": "Query platform-specific graphics APIs.\nRequires proper GPU drivers to be installed.\nSupported on Linux, FreeBSD, Windows and macOS" + }, + { + "const": "pci", + "description": "Search PCI devices, which does not require GPU drivers to be installed.\nNot supported on Windows and macOS" + }, + { + "const": "vulkan", + "description": "Use Vulkan API.\nSlow and requires proper Vulkan drivers to be installed.\nUsed for Android" + }, + { + "const": "opencl", + "description": "Use OpenCL API.\nSlow and requires proper OpenCL drivers to be installed" + }, + { + "const": "opengl", + "description": "Use OpenGL API.\nSlow and only detects one GPU.\nUsed for OpenBSD" + } ], - "default": "auto" + "default": "" }, "hideType": { "description": "Specify the type of GPUs should not be printed", - "enum": [ - "integrated", - "discrete", - "unknown", - "none" + "oneOf": [ + { + "const": null, + "description": "Do not hide any GPUs" + }, + { + "const": "none", + "description": "Do not hide any GPUs (kept for compatibility)" + }, + { + "const": "integrated", + "description": "Hide integrated GPUs" + }, + { + "const": "discrete", + "description": "Hide discrete GPUs" + }, + { + "const": "unknown", + "description": "Hide unknown (unrecognized) GPUs" + } ], - "default": "none" + "default": null }, "key": { "$ref": "#/$defs/key" @@ -2719,7 +2892,7 @@ "default": true }, "showAllIps": { - "description": "Show all IPs bound to the same interface.\nBy default only the first IP is shown", + "description": "Show all IPs bound to the same interface.\nBy default only the firstly detected IP is shown", "type": "boolean", "default": false }, @@ -2738,7 +2911,7 @@ "type": "string" }, "defaultRouteOnly": { - "description": "Show ips that are used for default routing only", + "description": "Show ips that are used for default routing only\nDoesn't work on Android", "type": "boolean", "default": true }, @@ -2986,7 +3159,7 @@ "type": "string" }, "defaultRouteOnly": { - "description": "Show ips that are used for default routing only", + "description": "Show ips that are used for default routing only\nDoesn't work on Android", "type": "boolean", "default": true }, @@ -2997,7 +3170,7 @@ }, "waitTime": { "type": "integer", - "description": "Wait time (in ms). Disk I/O = (totalBytesEnd - totalBytesStart) / waitTime", + "description": "Wait time (in ms). Net I/O = (totalBytesEnd - totalBytesStart) / waitTime", "default": 200, "minimum": 1 }, @@ -3067,10 +3240,19 @@ }, "library": { "description": "Set the OpenGL context creation library to use", - "enum": [ - "auto", - "egl", - "glx" + "oneOf": [ + { + "const": "auto", + "description": "Prefer EGL on *nix; prefer platform-specific implementation on others" + }, + { + "const": "egl", + "description": "Use EGL, which works on TTY" + }, + { + "const": "glx", + "description": "Use GLX, requires X session (*nix only)" + } ], "default": "auto" }, @@ -3397,10 +3579,10 @@ "default": "http://ipinfo.io/ip" }, "timeout": { - "description": "Time in milliseconds to wait for the public ip server to respond", + "description": "Time in milliseconds to wait for the public ip server to respond.\n0 to disable timeout", "type": "integer", "minimum": 0, - "default": "disabled (0)" + "default": 0 }, "ipv6": { "description": "Whether to use IPv6 for public IP detection server", @@ -3503,10 +3685,19 @@ "soundType": { "description": "Set what type of sound devices should be printed", "type": "string", - "enum": [ - "main", - "active", - "all" + "oneOf": [ + { + "const": "main", + "description": "Print only main sound devices" + }, + { + "const": "active", + "description": "Print only active sound devices" + }, + { + "const": "all", + "description": "Print all sound devices" + } ], "default": "main" }, @@ -4004,14 +4195,14 @@ "const": "weather" }, "location": { - "description": "The location to display", + "description": "The location to display\nMust be URI encoded (e.g., a whitespace must be encoded as \"+\")", "type": "string" }, "timeout": { - "description": "Time in milliseconds to wait for the weather server to respond", + "description": "Time in milliseconds to wait for the weather server to respond.\n0 to disable timeout", "type": "integer", "minimum": 0, - "default": "disabled (0)" + "default": 0 }, "outputFormat": { "description": "The output weather format to be used (must be URI encoded)",