Module tealdoc

local record tealdoc
  
interface DeclarationItem
    
enum Visibility
      "global"
      "local"
      "record"
end
    visibility: Visibility
end
  
record Env
    registry: {string : Item}
    modules: {string}
    include_all: boolean
    no_warnings_on_missing: boolean
    add_parser: function(self: Env, parser: Parser)
    add_tag: function(self: Env, tag: Tag)
    init: function(): Env
    parser_registry: {string : Parser}
    tag_registry: {string : Tag}
end
  
record FunctionItem
    
record Param
      name: string
      type: string
      description: string
end
    
record Return
      type: string
      description: string
end
    
enum FunctionKind
      "function"
      "macroexp"
      "metamethod"
end
    params: {Param}
    returns: {Return}
    typeargs: {Typearg}
    function_kind: FunctionKind
    is_declaration: boolean

end
  
interface Item
    kind: string
    path: string
    name: string
    children: {string}
    parent: string
    text: string
    attributes: {string : <any type>}
    location: Location
end
  
record Location
    filename: string
    x: integer
    y: integer
end
  
interface Parser
    process: function(self: Parser, text: string, path: string, env: tealdoc.Env)
    file_extensions: {string}
end
  
interface Plugin
    name: string
    run: function(env: tealdoc.Env)
end
  
interface Tag
    
interface Context
      item: Item
      param: string
      description: string
end
    name: string
    handle: function(ctx: Context)
    has_param: boolean
    has_description: boolean
end
  
record TypeItem
    
enum TypeKind
      "enum"
      "interface"
      "record"
      "type"
end
    typename: string
    typeargs: {Typearg}
    type_kind: TypeKind
    inherits: {string}

end
  
record Typearg
    name: string
    constraint: string
    description: string
end
  
record VariableItem
    typename: string

end
  process_file: function(path: string, env: Env)
  process_text: function(text: string, filename: string, env: Env)
  version: string
end

DeclarationItem

interface DeclarationItem
  
enum Visibility
    "global"
    "local"
    "record"
end
  visibility: Visibility
end

This interface represents a declaration item in Tealdoc. It is used to represent declarations of functions, variables, and types.

DeclarationItem.Visibility

enum DeclarationItem.Visibility
  "global"
  "local"
  "record"
end

Possible visibilities for declarations.

DeclarationItem.Visibility."global"

Global visibility, for global variables and functions.

DeclarationItem.Visibility."local"

Local visibility, for local variables and functions.

DeclarationItem.Visibility."record"

Record visibility, for record fields and nested types.

DeclarationItem.visibility

DeclarationItem.visibility: Visibility

The visibility of the declaration.

Env

record Env
  registry: {string : Item}
  modules: {string}
  include_all: boolean
  no_warnings_on_missing: boolean
  add_parser: function(self: Env, parser: Parser)
  add_tag: function(self: Env, tag: Tag)
  init: function(): Env
  parser_registry: {string : Parser}
  tag_registry: {string : Tag}
end

Env is the environment in which Tealdoc operates. It contains the registry of items, parsers, and tag handlers. You can use this environment to add new parsers or tag handlers. You can also use it to access the registry of items.

Env.registry

Env.registry: {string : Item}

The registry of items, which is a table mapping paths to items. This is used to store all the items that are processed by Tealdoc. The keys are the paths of the items, and the values are the items themselves.

Env.modules

Env.modules: {string}

The list of modules that are processed by Tealdoc. This is used to store the names of the modules that are documented.

Env.include_all

Env.include_all: boolean

The option to include all items in the output. If this is true, all items will be included in the output, regardless of whether they are local or global. When using the CLI, you can set this option using the --all flag.

Env.no_warnings_on_missing

Env.no_warnings_on_missing: boolean

Whether to skip warnings about missing items. If this is true, Tealdoc will not log warnings about missing items.

Env.add_parser

function Env.add_parser(self: Env, parser: Parser)

Add a parser to the environment. This function registers a parser that can handle specific file extensions. The parser must implement the tealdoc.Parser interface.

Parameters

• self (Env) — The environment to which the parser is added.
• parser (Parser) — The parser to add.

Env.add_tag

function Env.add_tag(self: Env, tag: Tag)

Add a tag to the environment. The tag must implement the tealdoc.Tag interface.

Parameters

• self (Env) — The environment to which the tag is added.
• tag (Tag) — The tag to add.

Env.init

function Env.init(): Env

Initialize a new environment. This function creates a new environment with empty registries.

Returns

1. (Env)

FunctionItem

record FunctionItem
  
record Param
    name: string
    type: string
    description: string
end
  
record Return
    type: string
    description: string
end
  
enum FunctionKind
    "function"
    "macroexp"
    "metamethod"
end
  params: {Param}
  returns: {Return}
  typeargs: {Typearg}
  function_kind: FunctionKind
  is_declaration: boolean

end

This record represents a function item in Tealdoc.

FunctionItem.Param

record FunctionItem.Param
  name: string
  type: string
  description: string
end

This record represents a parameter of a function.

FunctionItem.Param.name

FunctionItem.Param.name: string

The name of the parameter.

FunctionItem.Param.type

FunctionItem.Param.type: string

The type of the parameter.

FunctionItem.Param.description

FunctionItem.Param.description: string

The description of the parameter.

FunctionItem.Return

record FunctionItem.Return
  type: string
  description: string
end

This record represents a return value of a function.

FunctionItem.Return.type

FunctionItem.Return.type: string

The type of the return value.

FunctionItem.Return.description

FunctionItem.Return.description: string

The description of the return value.

FunctionItem.FunctionKind

enum FunctionItem.FunctionKind
  "function"
  "macroexp"
  "metamethod"
end

Possible function kinds

FunctionItem.FunctionKind."function"

Normal function, local, global, or in-record.

FunctionItem.FunctionKind."macroexp"

Macro expansion function

FunctionItem.FunctionKind."metamethod"

Record metamethod

FunctionItem.params

FunctionItem.params: {Param}

Function parameters.

FunctionItem.returns

FunctionItem.returns: {Return}

Function return values.

FunctionItem.typeargs

FunctionItem.typeargs: {Typearg}

Function type arguments.

FunctionItem.function_kind

FunctionItem.function_kind: FunctionKind

The kind of the function.

FunctionItem.is_declaration

FunctionItem.is_declaration: boolean

Whether this function is only a declaration (it does not contain a body).

Item

interface Item
  kind: string
  path: string
  name: string
  children: {string}
  parent: string
  text: string
  attributes: {string : <any type>}
  location: Location
end

Item is an abstract base interface for Tealdoc items. Items represent documentation entities such as functions, variables, types, etc. Items can also represent abstract concepts like namespaces or modules.

Item.kind

Item.kind: string

The kind of the item, e.g. "function", "variable", "type", etc. This is used to differentiate between different types of items.

Item.path

Item.path: string

The path to the item, which is used as a unique identifier.

Item.name

Item.name: string

The name of the item, which is used for display purposes. This is usually the same as the last part of the path.

Item.children

Item.children: {string}

The children of the item, which are other items that are related to this item. This is used to represent hierarchical relationships between items. For example, a record type may have fields that are also items. The children are stored as an array of paths of the children.

Item.parent

Item.parent: string

The parent of the item, which is the path to the parent item.

Item.text

Item.text: string

The text of the item, which is the documentation content. This is usually a multiline string that contains the documentation for the item. It may include markdown or other formatting. If the item does not have any documentation, this may be nil.

Item.attributes

Item.attributes: {string : <any type>}

The attributes of the item, which are additional metadata.

Item.location

Item.location: Location

The location of the item in the source code.

Location

record Location
  filename: string
  x: integer
  y: integer
end

This record represents a location in a file. It is used to store the location of an item in the source code.

Location.filename

Location.filename: string

The path to the file where the item is located.

Location.x

Location.x: integer

The column number where the item is located.

Location.y

Location.y: integer

The line number where the item is located.

Parser

interface Parser
  process: function(self: Parser, text: string, path: string, env: tealdoc.Env)
  file_extensions: {string}
end

Parser is an abstract base interface for Tealdoc parsers. Parsers are used to process source files and extract documentation items from them. Parsers must add the items to the env.registry table. Each parser is responsible for a specific set of file extensions. You can register a parser using the add_parser method of the tealdoc.Env interface.

Parser.process

function Parser.process(self: Parser, text: string, path: string, env: tealdoc.Env)

Process file contents. This function is called by Tealdoc when a file with a registered extension is processed.

Parameters

• self (Parser) — The parser instance.
• text (string) — The contents of the file as a string.
• path (string) — The path of the file being processed.
• env (tealdoc.Env) — The environment in which the parser is running.

Parser.file_extensions

Parser.file_extensions: {string}

A list of file extensions that this parser can handle. This is used to register the parser in the tealdoc.Env environment. Each extension should start with a dot (e.g. ".lua", ".md").

Plugin

interface Plugin
  name: string
  run: function(env: tealdoc.Env)
end

Plugin is an abstract base interface for tealdoc plugins. Plugins can be used to extend Tealdoc functionality. When using the CLI you can load plugins using the --plugin option followed by the plugin package name, which will be resolved the same way as Lua modules.

Plugin.name

Plugin.name: string

The name of the plugin used for identification purposes.

Plugin.run

function Plugin.run(env: tealdoc.Env)

Run the plugin. This function is called when the plugin is loaded. You may use this function to modify the environment in order to extend the Tealdoc functionality.

Parameters

• env (tealdoc.Env) — The environment in which the plugin is running.

Tag

interface Tag
  
interface Context
    item: Item
    param: string
    description: string
end
  name: string
  handle: function(ctx: Context)
  has_param: boolean
  has_description: boolean
end

Tag is an abstract base interface for Tealdoc tags. Tags are used to annotate items with additional metadata. Tags can be used to provide additional information about an item, such as parameters, descriptions, or other attributes. Tags can be registered in the tealdoc.Env environment using the add_tag method.

Tag.Context

interface Tag.Context
  item: Item
  param: string
  description: string
end

Context is the context in which the tag is encountered.

Tag.Context.item

Tag.Context.item: Item

The item to which the tag belongs.

Tag.Context.param

Tag.Context.param: string

The parameter of the tag if any. Only applicable if has_param of the tag is true.

Tag.Context.description

Tag.Context.description: string

The description of the tag if any. Only applicable if has_description of the tag is true.

Tag.name

Tag.name: string

The name of the tag, which is used to identify the tag in the comments.

Tag.handle

function Tag.handle(ctx: Context)

Function which is called when the tag is encountered in the comments.

Parameters

• ctx (Context) — The context in which the tag is encountered.

Tag.has_param

Tag.has_param: boolean

Whether the tag has a parameter. If true, the tag expects a parameter after the tag name. For example, @param name description has a parameter name.

Tag.has_description

Tag.has_description: boolean

Whether the tag has a description. If true, the tag expects a description after the tag name or parameter. For example, @description This is a description has a description This is a description.

TypeItem

record TypeItem
  
enum TypeKind
    "enum"
    "interface"
    "record"
    "type"
end
  typename: string
  typeargs: {Typearg}
  type_kind: TypeKind
  inherits: {string}

end

This record represents a type item in Tealdoc. It is used to represent types, records, interfaces, enums, and type aliases.

TypeItem.TypeKind

enum TypeItem.TypeKind
  "enum"
  "interface"
  "record"
  "type"
end

Possible kinds of types.

TypeItem.TypeKind."enum"

Type kind for an enum type.

TypeItem.TypeKind."interface"

Type kind for an interface type.

TypeItem.TypeKind."record"

Type kind for a record type.

TypeItem.TypeKind."type"

Type kind for a type alias.

TypeItem.typename

TypeItem.typename: string

The name of the type of the type item.

TypeItem.typeargs

TypeItem.typeargs: {Typearg}

The type arguments of the type item. Only used for records and interfaces.

TypeItem.type_kind

TypeItem.type_kind: TypeKind

The kind of the type item.

TypeItem.inherits

TypeItem.inherits: {string}

Names of inherited types

Typearg

record Typearg
  name: string
  constraint: string
  description: string
end

This record represents a type argument for a function or type.

Typearg.name

Typearg.name: string

The name of the type argument.

Typearg.constraint

Typearg.constraint: string

The constraint of the type argument if any.

Typearg.description

Typearg.description: string

The description of the type argument.

VariableItem

record VariableItem
  typename: string

end

This record represents a variable item in Tealdoc.

VariableItem.typename

VariableItem.typename: string

The name of the type of the variable.

process_file

function process_file(path: string, env: Env)

Process a file with the given path using the parsers registered in the environment. This function reads the file contents and passes it to the appropriate parser based on the file extension. If no parser is found for the file extension, a warning is logged and the file is skipped.

Parameters

• path (string) — The path to the file to process.
• env (Env) — The environment in which the file is processed.

process_text

function process_text(text: string, filename: string, env: Env)

Process the given text as a file with the specified filename using the parsers registered in the environment. This function is useful for processing text that is not read from a file, such as text from a string or a buffer. If no parser is found for the file extension, a warning is logged and the text is skipped.

Parameters

• text (string) — The text to process.
• filename (string) — The name of the file being processed, used to determine the file extension.
• env (Env) — The environment in which the text is processed.

version

version: string

Current version of Tealdoc.