From e2b791ea5ccc2438fa10c4874f8c8ab9d7829335 Mon Sep 17 00:00:00 2001 From: carsakiller Date: Tue, 14 Jun 2022 22:26:09 -0400 Subject: add: en-us descriptions for tags --- locale/en-us/script.lua | 445 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 443 insertions(+), 2 deletions(-) (limited to 'locale') diff --git a/locale/en-us/script.lua b/locale/en-us/script.lua index 6559e21d..56a11d52 100644 --- a/locale/en-us/script.lua +++ b/locale/en-us/script.lua @@ -549,7 +549,448 @@ CLI_CHECK_RESULTS = LUADOC_DESC_CLASS = [=[ -```lua ----@class [: [, , ...]] +Defines a class/table structure +## Syntax +`---@class [: [, ]...]` +## Usage ``` +---@class Manager: Person, Human +Manager = {} +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#class) +]=] +LUADOC_DESC_TYPE = +[=[ +Specify the type of a certain variable + +Default types: `nil`, `any`, `boolean`, `string`, `number`, `integer`, +`function`, `table`, `thread`, `userdata`, `lightuserdata` + +(Custom types can be provided using `@alias`) + +## Syntax +`---@type [| [type]...` + +## Usage +### General +``` +---@type nil|table|myClass +local Example = nil +``` + +### Arrays +``` +---@type number[] +local phoneNumbers = {} +``` + +### Enums +``` +---@type "red"|"green"|"blue" +local color = "" +``` + +### Tables +``` +---@type table +local settings = { + disableLogging = true, + preventShutdown = false, +} + +---@type { [string]: true } +local x --x[""] is true +``` + +### Functions +``` +---@type fun(mode?: "r"|"w"): string +local myFunction +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#types-and-type) +]=] +LUADOC_DESC_ALIAS = +[=[ +Create your own custom type that can be used with `@param`, `@type`, etc. + +## Syntax +`---@alias [description]`\ +or +``` +---@alias +---| 'value' [# comment] +---| 'value2' [# comment] +... +``` + +## Usage +### Expand to other type +``` +---@alias filepath string Path to a file + +---@param path filepath Path to the file to search in +function find(path, pattern) end +``` + +### Enums +``` +---@alias font-style +---| '"underlined"' # Underline the text +---| '"bold"' # Bolden the text +---| '"italic"' # Make the text italicized + +---@param style font-style Style to apply +function setFontStyle(style) end +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#alias) +]=] +LUADOC_DESC_PARAM = +[=[ +Declare a function parameter + +## Syntax +`@param [?] [comment]` + +## Usage +### General +``` +---@param url string The url to request +---@param headers? table HTTP headers to send +---@param timeout? number Timeout in seconds +function get(url, headers, timeout) end +``` + +### Variable Arguments +``` +---@param base string The base to concat to +---@param ... string The values to concat +function concat(base, ...) end +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#param) +]=] +LUADOC_DESC_RETURN = +[=[ +Declare a return value + +## Syntax +`@return [name] [description]`\ +or\ +`@return [# description]` + +## Usage +### General +``` +---@return number +---@return number # The green component +---@return number b The blue component +function hexToRGB(hex) end +``` + +### Type & name only +``` +---@return number x, number y +function getCoords() end +``` + +### Type only +``` +---@return string, string +function getFirstLast() end +``` + +### Return variable values +``` +---@return string ... The tags of the item +function getTags(item) end +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#return) +]=] +LUADOC_DESC_FIELD = +[=[ +Decalare a field in a class/table. This allows you to provide more in-depth +documentation for a table. + +## Syntax +`---@field [description]` + +## Usage +``` +---@class HTTP_RESPONSE +---@field status HTTP_STATUS +---@field headers table The headers of the response + +---@class HTTP_STATUS +---@field code number The status code of the response +---@field message string A message reporting the status + +---@return HTTP_RESPONSE response The response from the server +function get(url) end + +--This response variable has all of the fields defined above +response = get("localhost") + +--Extension provided intellisense for the below assignment +statusCode = response.status.code +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#field) +]=] +LUADOC_DESC_GENERIC = +[=[ +Simulates generics. Generics can allow types to be re-used as they help define +a "generic shape" that can be used with different types. + +## Syntax +`---@generic [:parent_type] [, [:parent_type]]` + +## Usage +### General +``` +---@generic T +---@param value T The value to return +---@return T value The exact same value +function echo(value) + return value +end + +-- Type is string +s = echo("e") + +-- Type is number +n = echo(10) + +-- Type is boolean +b = echo(true) + +-- We got all of this info from just using +-- @generic rather than manually specifying +-- each allowed type +``` + +### Capture name of generic type +``` +---@class Foo +local Foo = {} +function Foo:Bar() end + +---@generic T +---@param name `T` # the name generic type is captured here +---@return T # generic type is returned +function Generic(name) end + +local v = Generic("Foo") -- v is an object of Foo +``` + +### How Lua tables use generics +``` +---@class table: { [K]: V } + +-- This is what allows us to create a table +-- and intellisense keeps track of any type +-- we give for key (K) or value (V) +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#generics-and-generic) +]=] +LUADOC_DESC_VARARG = +[=[ +Primarily for legacy support for EmmyLua annotations. `@vararg` does not +provide typing or allow descriptions. + +**You should instead use `@param` when documenting parameters (variable or not).** + +## Syntax +`@vararg ` + +## Usage +``` +---Concat strings together +---@vararg string +function concat(...) end +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#vararg) +]=] +LUADOC_DESC_OVERLOAD = +[=[ +Allows defining of multiple function signatures. + +## Syntax +`---@overload fun([: ] [, [: ]]...)[: [, ]...]` + +## Usage +``` +---@overload fun(t: table, value: any): number +function table.insert(t, position, value) end +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#overload) +]=] +LUADOC_DESC_DEPRECATED = +[=[ +Marks a function as deprecated. This results in any deprecated function calls +being ~~struck through~~. + +## Syntax +`---@deprecated` + +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#deprecated) +]=] +LUADOC_DESC_META = +[=[ +Indicates that this is a meta file and should be used for definitions and intellisense only. + +There are 3 main distinctions to note with meta files: +1. There won't be any context-based intellisense in a meta file +2. Hovering a `require` filepath in a meta file shows `[meta]` instead of an absolute path +3. The `Find Reference` function will ignore meta files + +## Syntax +`---@meta` + +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#meta) +]=] +LUADOC_DESC_VERSION = +[=[ +Specifies Lua versions that this function is exclusive to. + +Lua versions: `5.1`, `5.2`, `5.3`, `5.4`, `JIT`. + +Requires configuring the `Diagnostics: Needed File Status` setting. + +## Syntax +`---@version [, ]...` + +## Usage +### General +``` +---@version JIT +function onlyWorksInJIT() end +``` +### Specify multiple versions +``` +---@version <5.2,JIT +function oldLuaOnly() end +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#version) +]=] +LUADOC_DESC_SEE = +[=[ +Define something that can be viewed for more information + +## Syntax +`---@see ` + +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#see) +]=] +LUADOC_DESC_DIAGNOSTIC = +[=[ +Enable/disable diagnostics for error/warnings/etc. + +Actions: `disable`, `enable`, `disable-line`, `disable-next-line` + +[Names](https://github.com/sumneko/lua-language-server/blob/cbb6e6224094c4eb874ea192c5f85a6cba099588/script/proto/define.lua#L54) + +## Syntax +`---@diagnostic [: ]` + +## Usage +### Disable next line +``` +---@diagnostic disable-next-line: undefined-global +``` + +### Manually toggle +``` +---@diagnostic disable: unused-local +local unused = "hello world" +---@diagnostic enable: unused-local +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#diagnostic) +]=] +LUADOC_DESC_MODULE = +[=[ +Provides the semantics of `reqire`. + +## Syntax +`---@module <'module_name'>` + +## Usage +``` +---@module 'string.utils' +local stringUtils +-- This is functionally the same as: +local module = require('string.utils') +``` +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#module) +]=] +LUADOC_DESC_ASYNC = +[=[ +Marks a function as asynchronous. + +## Syntax +`---@async` + +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#async) +]=] +LUADOC_DESC_NODISCARD = +[=[ +Prevents this function's return values from being discarded/ignored. +This will raise the `discard-returns` warning should the return values +be ignored. + +## Syntax +`---@nodiscard` + +--- +[View Wiki](https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#nodiscard) +]=] +LUADOC_DESC_CAST = +[=[ +Allows type casting (type conversion). + +⚠️ **Not Finalized** + +## Syntax +`@cast <[+|-]type>[, <[+|-]type>]...` + +## Usage +### Overwrite type +``` +---@type integer +local x --> integer + +---@cast x string +print(x) --> string +``` +### Add Type +``` +---@type string +local x --> string + +---@cast x +boolean, +number +print(x) --> string|boolean|number +``` +### Remove Type +``` +---@type string|table +local x --> string|table + +---@cast x -string +print(x) --> table +``` +--- +[View Proposal](https://github.com/sumneko/lua-language-server/issues/1030) ]=] -- cgit v1.2.3