Contributing to Documentation
Help improve ACE documentation by writing source-verified function docs and LDoc annotations
LDoc Format Reference
If you're adding documentation directly to the source code (the preferred method for permanent changes), use LDoc-style annotations. Functions with annotations are automatically marked as verified when parsed.
Why annotate the source?
Annotations live in the source code, so they stay up-to-date with the implementation. Our parser automatically extracts them and marks the documentation as verified.
What the ACE parser supports
We support a practical subset of LDoc plus EmmyLua-style annotations — whichever ACE source already uses. Both -- @tag and ---@tag prefixes work. Recognized tags: @param, @tparam, @return, @treturn, @see, @usage, @module, @classmod, @within. Full tag spec lives in the official LDoc manual.
Basic Example
--- Calculate damage after armor penetration.
-- This function applies the ACE damage model to determine
-- how much damage passes through armor.
-- @param ent Entity The entity being damaged
-- @param damage number The incoming damage amount
-- @param hitPos Vector World position of the hit
-- @return number The actual damage dealt
-- @return boolean Whether the armor was penetrated
function ACF.CalcDamage(ent, damage, hitPos)
-- implementation
endComment Style
---Starts the doc block (3 dashes)--Continues the doc block (2 dashes)- EmmyLua
---@taglines are also recognized - First line = summary (should end with period)
- Following lines = detailed description
Common Tags
@param name type Description@return type Description@see OtherFunction@usage+ example code
Advanced Example with Usage
--- Fire a projectile from a weapon.
-- Creates and launches a projectile entity with the specified parameters.
-- The projectile will inherit the owner from the gun entity.
-- @param gun Entity The weapon firing the projectile
-- @param pos Vector Spawn position for the projectile
-- @param dir Vector Direction vector (will be normalized)
-- @param velocity number Initial velocity in units/second
-- @param caliber number? Optional caliber override (defaults to gun caliber)
-- @return Entity The spawned projectile entity
-- @return boolean Whether the spawn was successful
-- @see ACF.GetCaliber
-- @usage
-- local proj, success = ACF.FireProjectile(
-- self.Gun,
-- self:GetMuzzlePos(),
-- self:GetAimVector(),
-- 800
-- )
-- if success then
-- proj:SetOwner(self:GetOwner())
-- end
function ACF.FireProjectile(gun, pos, dir, velocity, caliber)
-- implementation
endOptional Parameters
Any of these mark a parameter as optional (all are recognized by the parser):
-- Method 1: LDoc [opt] modifier (attached to the tag, no space)
-- @param[opt] options The configuration table
-- @tparam[opt=5] number count Defaults to 5
-- Method 2: Question mark suffix on the type or name
-- @param caliber number? Optional caliber override
-- @param caliber? number Optional caliber override
-- Method 3: the word "optional" in the description
-- @param options table Optional configuration tableNote: [opt] must touch the tag (@param[opt], not@param [opt]) — that's the LDoc convention.