This annotation is intended for complex cases and is primarily designed to be used by the built-in annotations.
Overview
Use@call_arg when your function wraps a Garry’s Mod API. It lets completion, navigation, type checking, and other editor features treat the wrapper like the original function.
The official annotations already apply it to built-in functions like include, AddCSLuaFile, file.Find, util.AddNetworkString, net.Start, hook.Add, vgui.Register, and derma.DefineSkin.
Only add it when the wrapper has the same behavior as the API it represents.
Wrappers that call the standard GMod network functions are detected automatically. You do not need
@call_arg for normal net.Start, net.Receive, read, write, or send wrappers.Syntax
@call_arg directly above the @param it describes.
path argument as a file loaded by include.
For overloaded signatures, use @overload_call_arg directly above the @overload it describes:
@call_arg_field with the field’s path:
panel.Base is treated as the panel’s base class. Use dots for nested fields, such as "Options.Base".
@overload_call_arg_field does the same for a parameter inside the following @overload. It takes the zero-based parameter index first:
Supported roles
A
gmod.member_guard wrapper takes the name of the member it checks:
@valid_guard, @self_guard and @self_call_valid.
Hooks with callbacks
Use one role for the hook name and one role for the callback function:emit for functions that call hooks:
Lua loading
Usegmod.load for wrappers around Lua file and module loading:
include, AddCSLuaFile, IncludeCS, and require calls. GLuaLS follows fixed paths and file.Find loops when it can identify the matching files.
Use gmod.file_find when wrapping file.Find itself:
FindLuaFiles("myaddon/*.lua", "LUA") is used in a loop and the loop body calls annotated load wrappers, GLuaLS can infer which matching files are loaded server-side, sent to the client, or shared.
Use compilefile for CompileFile wrappers, and gmod.environment for setfenv wrappers. When a compiled file is given an environment table, globals in that file are looked up in the table:
CompileFile, the path is relative to lua/, not to the calling file.
VGUI panels
Usedefine, table, and base for a vgui.Register wrapper:
define_control instead of define for derma.DefineControl wrappers. Use reference for functions that create or look up panels by name.
Other panel roles:
register_filemarks a file path whosePANELtable is registered, likevgui.RegisterFile.register_tablemarks a panel table that is created or registered without a name, likevgui.CreateFromTableandvgui.RegisterTable.parentmarks the parent panel argument, like theparentofvgui.Create.child_selfmarks a method that sets the parent of the panel it is called on, likePanel:SetParent.parent_selfmarks a method that parents its argument to the panel it is called on, likePanel:Add.own_classmarks a parameter that receives the panel’s own class name, like theclassofPANEL:GenerateExample.
self:GetParent() in a child panel has the parent’s type.
Derma skins
Usegmod.derma_skin when wrapping Derma skin functions:
DefineSkin("MySkin", ...) and UseSkin("MySkin").
Scripted classes
Usegmod.network_var when wrapping entity NetworkVar helpers:
define_element for wrappers around NetworkVarElement, because element accessors always return numbers. Use define_slot for DTVar-style functions that register a named data table slot.
Use gmod.scripted_class for functions that register entities or weapons by name:
weapon_table instead of entity_table for weapons. The table then becomes the class named by className, with its base class’s fields and methods.
For IsBasedOn-style checks, mark the class name with class_name and the base with based_on. Inside if IsBasedOn(ent:GetClass(), "base_class") then, ent has the base class’s type. The class name has to come from a method marked with @self_class_name, such as Entity:GetClass.
For gamemode inheritance wrappers, mark the base-name parameter:
gmod.class_base reference for wrappers around DEFINE_BASECLASS.
Priority
An optional third argument breaks ties when one parameter can inherit multiple roles:See also
@valid_guard: validity checks for nil and NULL warnings