l0.MoonCats.annotations¶

MoonScriptLua

annotations = require "l0.MoonCats.annotations"

local annotations = require("l0.MoonCats.annotations")

A LuaCATS @param tag's parsed contract.

Functions¶

extractTypeText ¶

MoonScriptLua

annotations.extractTypeText text

annotations.extractTypeText(text)

Extracts the leading type expression from a tag line remainder, balancing brackets so function types, inline tables, and generics survive; a token ending in ":" or "," pulls in the next token (fun return lists).

param	type	description
text	`string`	Everything after the tag's name field.

Returns:

typeText string — The type expression, or "any" when none could be read.
restText string — The remainder following the type expression, whitespace-trimmed.

parseParamTag ¶

MoonScriptLua

annotations.parseParamTag line

annotations.parseParamTag(line)

Parses a ---@param tag line into its contract.

param	type	description
line	`string`

Returns:

tag MoonCatsParamTag? — Nil when the line is not a @param tag.

parseReturnTag ¶

MoonScriptLua

annotations.parseReturnTag line

annotations.parseReturnTag(line)

Parses a ---@return tag line into its contract. The first word after the type is taken as the return's name, matching how the language server reads the tag.

param	type	description
line	`string`

Returns:

tag MoonCatsReturnTag? — Nil when the line is not a @return tag.

parseFieldTag ¶

MoonScriptLua

annotations.parseFieldTag line

annotations.parseFieldTag(line)

Parses a ---@field tag line into its contract, honoring a leading visibility keyword.

param	type	description
line	`string`

Returns:

tag MoonCatsFieldTag? — Nil when the line is not a @field tag.

parseAliasVariants ¶

MoonScriptLua

annotations.parseAliasVariants blockLines

annotations.parseAliasVariants(blockLines)

Parses an @alias declaration's ---| variant lines.

param	type	description
blockLines	`string`[]	The alias segment's lines (non-variant lines are skipped).

Returns:

variants MoonCatsAliasVariant[] — In declaration order.

collectBlockTags ¶

MoonScriptLua

annotations.collectBlockTags blockLines

annotations.collectBlockTags(blockLines)

Collects the @param and @return tags of an annotation block.

param	type	description
blockLines?	`string`[]

Returns:

params MoonCatsParamTag[] — In tag order.
returns MoonCatsReturnTag[] — In tag order.

blockDocumentsFunction ¶

MoonScriptLua

annotations.blockDocumentsFunction blockLines

annotations.blockDocumentsFunction(blockLines)

Reports whether an annotation block documents a function (has @param or @return tags).

param	type	description
blockLines?	`string`[]

Returns:

documentsFunction boolean

blockContainsPrivateTag ¶

MoonScriptLua

annotations.blockContainsPrivateTag blockLines

annotations.blockContainsPrivateTag(blockLines)

Reports whether a block already carries an @private tag.

param	type	description
blockLines?	`string`[]

Returns:

tagged boolean

proseLines ¶

MoonScriptLua

annotations.proseLines blockLines

annotations.proseLines(blockLines)

Collects a block's prose lines (untagged, non-variant), stripped of the comment lead but otherwise verbatim: indentation and blank separator lines survive, so markdown constructs like indented code examples keep working. Boundary blank lines are trimmed.

param	type	description
blockLines?	`string`[]

Returns:

lines string[] — In block order; empty when the block has no prose.

flattenBlockProse ¶

MoonScriptLua

annotations.flattenBlockProse blockLines

annotations.flattenBlockProse(blockLines)

Joins a block's prose lines into a single-line description for a @field tag.

param	type	description
blockLines?	`string`[]

Returns:

prose string — Empty when the block has no prose.

blockOwnType ¶

MoonScriptLua

annotations.blockOwnType blockLines

annotations.blockOwnType(blockLines)

Extracts the type expression of a block's own @type tag.

param	type	description
blockLines?	`string`[]

Returns:

typeText string? — Nil when the block carries no @type tag.

blockTagText ¶

MoonScriptLua

annotations.blockTagText blockLines, tag

annotations.blockTagText(blockLines, tag)

Extracts the text of a block's first occurrence of the given tag.

param	type	description
blockLines?	`string`[]
tag	`string`	Tag name without the @ (e.g. "deprecated", "see").

Returns:

text string? — The tag's trailing text, empty for a bare tag, or nil when the tag is absent.

guardFunType ¶

MoonScriptLua

annotations.guardFunType typeText

annotations.guardFunType(typeText)

Parenthesizes a type expression containing a fun type, whose return list would otherwise swallow the comma before the next parameter or return in an assembled signature.

param	type	description
typeText	`string`

Returns:

safeText string

inferLiteralType ¶

MoonScriptLua

annotations.inferLiteralType token, literalKind

annotations.inferLiteralType(token, literalKind)

Infers a LuaCATS type for a literal token.

param	type	description
token	`string`
literalKind	`string`	Lua type name from the parser.

Returns:

typeText string

inferExpressionType ¶

MoonScriptLua

annotations.inferExpressionType node

annotations.inferExpressionType(node)

Guesses a numeric or string result type for an operator expression from its leaf nodes.

param	type	description
node	`table`

Returns:

typeText string — "number" or "string" from the leaf nodes, or "any" when neither appears.

Types¶

MoonCatsParamTag ¶

A LuaCATS @param tag's parsed contract.

field	type	description
name	`string`	Parameter name with any trailing ? stripped.
optional	`boolean`
type	`string`	The parameter's type expression.

MoonCatsReturnTag ¶

A LuaCATS @return tag's parsed contract.

field	type	description
type	`string`	The return's type expression.
name?	`string`	The return's name, when documented.
description?	`string`	Description text following the name.

MoonCatsFieldTag ¶

A LuaCATS @field tag's parsed contract.

field	type	description
name	`string`	Field name with any trailing ? stripped.
optional	`boolean`
visibility?	`string`	"private", "protected", "public", or "package" when tagged.
type	`string`	The field's type expression.
description?	`string`	Description text following the type.

MoonCatsAliasVariant ¶

One variant line of an @alias declaration.

field	type	description
value	`string`	The variant's literal value, verbatim.
key?	`string`	The member name from a "# Key: description" comment.
description?	`string`	The comment's description text.