Developer documentation
In-game documentation
Typing a cvar's name in the console prints what it does. That text is xdocs, and it is written separately from the cvar's registration.
Two places a description can come from
When the console prints a cvar, the engine asks the UI module for a description first, and
falls back to the string in the cvar’s own registration
(Cvar_DescriptionString):
- xdocs, compiled into the UI module from
ui_xdocs.h, which is richer and able to enumerate values - The registration string, the last argument to
Cvar_Get: one line, no structure - Nothing, if neither exists
So xdocs do not replace a good registration description; they are the longer form shown to somebody who is already in the console trying to work the cvar out. Write both.
Because xdocs live in the UI module, they travel with it. Load another mod’s ui
library, such as JA+’s, as install
describes. That module answers the engine instead, so TaystJK’s in-game help is gone
until you switch back.
Writing an entry
Entries are macro calls in ui_xdocs.h. The common case is a name, a short description and
an empty long one:
XDOCS_CVAR_DEF("cg_zoomFov", "The field of view when using +zoom", "")
The third argument is the long form, and it is where values get enumerated. SETTING takes
a value and what it means, and NL separates lines:
XDOCS_CVAR_DEF("cg_alwaysShowAbsorb", "Show absorb when it's in use",
SETTING("0", "Absorb shows only when used against another power (Base behavior)") NL
SETTING("1", "Absorb shows always when in use")
)
Typing the cvar’s name prints the short and long descriptions together
(cvar.cpp). The short one on its own appears in
cvarlist and in tab completion.
Which macro
| Macro | For |
|---|---|
XDOCS_CVAR_DEF |
An ordinary cvar |
XDOCS_CMD_DEF |
A command: name and one description, no values |
XDOCS_CVAR_BITFLAG_DEF |
A bitmask cvar |
XDOCS_CVAR_KEYVALUE_DEF |
A cvar taking key=value pairs |
XDOCS_CVAR_BITVALUE_DEF |
A bitmask whose entry also carries exec text |
In the help the client builds, the bitflag and keyvalue variants produce the same entry as
XDOCS_CVAR_DEF
(ui_xdocs.h). ui_xdocs.h also has header text that
explains how to combine flags or write key/value pairs, but only a list mode the client does
not build uses it. Use the variant that matches the cvar so the entry records its shape, and
still say in your own lines how the values combine.
Inside a long description, the helpers mirror what a reader sees:
| Helper | Describes |
|---|---|
SETTING(value, text) |
One possible value |
BITFLAG(text) |
One bit of a bitmask |
KEY(key, text) / KEYVALUE(key, format, text) |
One key in a key/value cvar |
SPECIAL(token, text) |
A value that behaves unlike the rest, such as -1 |
EXAMPLE(text, meaning) |
A worked example |
Coverage
119 of 1,445 cvars have an entry. The console reference tracks this per entry: each detail page shows an xdocs badge, and the search filters include Has xdocs entry and Missing from xdocs, so the gap is a list you can work from, not a guess.
That filter is the fastest way to find something worth writing. Start with a cvar you already understand, and prefer the ones players actually set.
When you add a cvar
An xdocs entry is on the contributing checklist, along with the registration description, the CHANGELOG line, and a menu entry where one makes sense.
Last changed History Edit this page on GitHub