mirror of
https://github.com/brues-code/ClassicAPI.git
synced 2026-11-17 16:34:41 +00:00
docs/API.md is 18.7k lines and its anchors are signature slugs, so editing a signature breaks the 281 internal and 88 README links into it. Blizzard solved the same problem by shipping the API as data plus a browser addon, and warcraft.wiki.gg renders those same tables. One set of descriptors can feed all three. Each registration now carries one next to it: typed arguments and returns, nilability, defaults, and a sentence. Events, enumerations and returned table shapes are described the same way. No Script_* body changed. Game.h gains namespace Game::Doc (Field with Req/Opt/Vararg, FieldList, Function, Method, Structure, Event) and a trailing descriptor argument on all six Game::Lua::Register* plus Event::Custom::AutoReserve. api/Documentation.cpp records every registration on the first pass of each Lua state and seals it, so /reload re-registers but records nothing and the environment comes from which pass saw the name. Export is lazy: nothing is materialized until C_APIDocumentation.GetSystem asks for one system, because eager export would build thousands of tables per reload for a slash command. _classicapi_UndocumentedAPI lists what still has no descriptor. AddOns/!!!ClassicAPI/APIDocumentation/ ports Blizzard_APIDocumentation's eight files. Named /classicapi, not /api: the browser holds only what ClassicAPI adds, so /api would have implied the whole 1.12 surface. Two deliberate differences from the retail source, both noted in the file headers: a system search also matches its namespace, since that is the name people type; and an undocumented function says so, because an empty signature otherwise reads as a real one. LinkUtil gains the SetItemRef to LinkUtil.ProcessLink dispatch. That handler registry was dead code; a new link type now registers a handler instead of stacking another SetItemRef override. Also defines assertsafe there, which was undefined and only mattered once the function went live. Documented: the C_Spell and C_SpellBook surface, the spell globals, both spellbook enumerations, the 13 UNIT_SPELLCAST_* events, GameTooltip as the widget-method example and C_Glue as the glue and mixed-environment example. 66 of 692 function registrations. tools/New-ApiDocSkeletons.ps1 emits paste-ready skeletons to make the rest of the sweep tractable. Verified in game: the browser lists, searches, and prints detail; links render and click through; right-click copies and shift-click dumps.
212 lines
9.0 KiB
PowerShell
212 lines
9.0 KiB
PowerShell
<#
|
|
.SYNOPSIS
|
|
Emits paste-ready `Game::Doc` descriptor skeletons for registrations that
|
|
do not have one yet.
|
|
|
|
.DESCRIPTION
|
|
Every `Game::Lua::Register*` call can carry a documentation descriptor (see
|
|
`namespace Game::Doc` in src/Game.h). Roughly 700 registrations still need
|
|
one. This script does the mechanical part of each: it finds the registered
|
|
names in a source file, recovers the argument list from that file's
|
|
`Usage:` strings, recovers a summary from the function's section in
|
|
docs/API.md, and writes a skeleton you paste into the file.
|
|
|
|
It writes ONLY into build/docskel. It never edits src/.
|
|
|
|
Every guess it makes is marked `// TODO`. A skeleton is a starting point,
|
|
not an answer: the `Script_*` body is the authority on the real signature,
|
|
and docs/API.md is stale in places. Read the body, fix the skeleton, then
|
|
paste it.
|
|
|
|
.PARAMETER Path
|
|
Source files to process. Accepts globs. Defaults to every .cpp under src.
|
|
|
|
.PARAMETER OutDir
|
|
Where to write the skeletons. Defaults to build/docskel.
|
|
|
|
.EXAMPLE
|
|
./tools/New-ApiDocSkeletons.ps1 -Path src/item/*.cpp
|
|
Writes build/docskel/item/<file>.skel.cpp for each item module.
|
|
#>
|
|
[CmdletBinding()]
|
|
param(
|
|
[string[]] $Path = @('src/**/*.cpp'),
|
|
[string] $OutDir = 'build/docskel'
|
|
)
|
|
|
|
$ErrorActionPreference = 'Stop'
|
|
$repo = Split-Path -Parent $PSScriptRoot
|
|
Set-Location $repo
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# docs/API.md: heading -> first sentence of the paragraph under it.
|
|
# Headings look like: ### `C_Spell.GetSpellInfo(spellID)`
|
|
# or a combined pair: ### `IsUsableSpell(spell)` / `IsUsableSpell(slot, ...)`
|
|
# ---------------------------------------------------------------------------
|
|
function Read-ApiSummaries {
|
|
$summaries = @{}
|
|
$lines = Get-Content 'docs/API.md' -Encoding UTF8
|
|
for ($i = 0; $i -lt $lines.Count; $i++) {
|
|
if ($lines[$i] -notmatch '^###\s+(.+)$') { continue }
|
|
$heading = $Matches[1]
|
|
|
|
# Every `Name(...)` in the heading maps to the same summary.
|
|
$names = [regex]::Matches($heading, '`([A-Za-z_][A-Za-z0-9_.:]*)\s*\(') |
|
|
ForEach-Object { $_.Groups[1].Value }
|
|
if (-not $names) { continue }
|
|
|
|
# First non-blank prose line after the heading, trimmed to one sentence.
|
|
$summary = $null
|
|
for ($j = $i + 1; $j -lt [Math]::Min($i + 8, $lines.Count); $j++) {
|
|
$line = $lines[$j].Trim()
|
|
if (-not $line) { continue }
|
|
if ($line -match '^(```|\||>|#|-\s)') { break }
|
|
$summary = $line
|
|
break
|
|
}
|
|
if (-not $summary) { continue }
|
|
if ($summary -match '^(.+?[.!?])(\s|$)') { $summary = $Matches[1] }
|
|
$summary = $summary -replace '\[([^\]]+)\]\([^)]+\)', '$1' `
|
|
-replace '[`*]', '' -replace '"', '\"'
|
|
|
|
foreach ($n in $names) {
|
|
$short = ($n -split '\.')[-1]
|
|
if (-not $summaries.ContainsKey($short)) { $summaries[$short] = $summary }
|
|
}
|
|
}
|
|
return $summaries
|
|
}
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Argument-name -> Blizzard type guess. Anything unmatched is TODO.
|
|
# ---------------------------------------------------------------------------
|
|
function Get-TypeGuess([string] $name) {
|
|
switch -Regex ($name) {
|
|
'^unit' { return 'UnitToken' }
|
|
'^(spell|spellIdentifier)$' { return 'SpellIdentifier' }
|
|
'^(item|itemIdentifier|itemInfo)$' { return 'ItemInfo' }
|
|
'(ID|Id|Index|Count|Slot|Level|Amount|Duration|Rate|Time)$' { return 'number' }
|
|
'^(index|slot|count|level|duration)$' { return 'number' }
|
|
'^(name|link|text|token|path|texture|locale|type|bookType)$' { return 'string' }
|
|
'^(is|has|can|does|should)[A-Z]' { return 'bool' }
|
|
default { return 'TODO' }
|
|
}
|
|
}
|
|
|
|
# Parse the inside of a `Usage:` signature into Doc::Req / Doc::Opt lines.
|
|
# `[, x]` marks the start of the optional tail; `...` is a vararg.
|
|
function ConvertTo-Fields([string] $argText) {
|
|
$fields = @()
|
|
if (-not $argText.Trim()) { return $fields }
|
|
|
|
$optionalFrom = $argText.IndexOf('[')
|
|
$clean = $argText -replace '[\[\]]', ''
|
|
$parts = $clean -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ }
|
|
|
|
$consumed = 0
|
|
foreach ($p in $parts) {
|
|
$bare = $p -replace '^"', '' -replace '"$', ''
|
|
$consumed += $p.Length
|
|
if ($bare -eq '...') {
|
|
$fields += ' Game::Doc::Vararg("TODO"), // TODO: type'
|
|
continue
|
|
}
|
|
$type = Get-TypeGuess $bare
|
|
$todo = if ($type -eq 'TODO') { ' // TODO: type' } else { '' }
|
|
$isOptional = $optionalFrom -ge 0 -and $argText.IndexOf($p) -gt $optionalFrom
|
|
if ($isOptional) {
|
|
$fields += " Game::Doc::Opt(`"$bare`", `"$type`"),$todo"
|
|
} else {
|
|
$fields += " Game::Doc::Req(`"$bare`", `"$type`"),$todo"
|
|
}
|
|
}
|
|
return $fields
|
|
}
|
|
|
|
$summaries = Read-ApiSummaries
|
|
Write-Host "docs/API.md: $($summaries.Keys.Count) summaries indexed"
|
|
|
|
$files = @()
|
|
foreach ($p in $Path) { $files += Get-ChildItem -Path $p -File -Recurse -ErrorAction SilentlyContinue }
|
|
$files = $files | Sort-Object FullName -Unique
|
|
|
|
$written = 0
|
|
foreach ($file in $files) {
|
|
$text = Get-Content $file.FullName -Raw
|
|
$rel = $file.FullName.Substring($repo.Length + 1) -replace '\\', '/'
|
|
|
|
# Registrations that already carry a descriptor end with `, &kSomething)`.
|
|
$globals = [regex]::Matches($text, 'RegisterGlobalFunction\(\s*"([^"]+)"\s*,\s*&(\w+)\s*\)')
|
|
$glue = [regex]::Matches($text, 'RegisterGlueFunction\(\s*"([^"]+)"\s*,\s*&(\w+)\s*\)')
|
|
$tables = [regex]::Matches($text, 'RegisterTableFunction\(\s*"([^"]+)"\s*,\s*"([^"]+)"\s*,\s*&(\w+)\s*\)')
|
|
if ($globals.Count + $glue.Count + $tables.Count -eq 0) { continue }
|
|
|
|
# `Usage: Name(a [, b])` strings, keyed by the bare function name.
|
|
$usage = @{}
|
|
foreach ($m in [regex]::Matches($text, 'Usage:\s*([A-Za-z_][A-Za-z0-9_.:]*)\s*\(([^)"]*)\)')) {
|
|
$short = ($m.Groups[1].Value -split '[.:]')[-1]
|
|
if (-not $usage.ContainsKey($short)) { $usage[$short] = $m.Groups[2].Value }
|
|
}
|
|
|
|
$out = New-Object System.Collections.Generic.List[string]
|
|
$out.Add("// Descriptor skeletons for $rel")
|
|
$out.Add('//')
|
|
$out.Add('// Paste into the file''s anonymous namespace, under a')
|
|
$out.Add('// // --- Documentation ---')
|
|
$out.Add('// banner, then add the `&kName` argument to each Register* call.')
|
|
$out.Add('//')
|
|
$out.Add('// VERIFY EVERY LINE against the Script_* body. Types and optionality are')
|
|
$out.Add('// guessed from the Usage: string; summaries come from docs/API.md, which')
|
|
$out.Add('// is stale in places. The body is the authority.')
|
|
$out.Add('')
|
|
|
|
$emit = {
|
|
param($luaName, $system)
|
|
$short = ($luaName -split '\.')[-1]
|
|
# One symbol per REGISTERED NAME, not per short name: a global and a
|
|
# table function often share a short name and would collide.
|
|
$sym = 'k' + (($luaName -replace '[^A-Za-z0-9]', ''))
|
|
$summary = if ($summaries.ContainsKey($short)) { $summaries[$short] } else { 'TODO: one sentence.' }
|
|
$argText = if ($usage.ContainsKey($short)) { $usage[$short] } else { $null }
|
|
|
|
$out.Add("// $luaName")
|
|
if ($null -eq $argText) {
|
|
$out.Add("// TODO: no Usage: string found - read the Script_* body for the arguments.")
|
|
}
|
|
$fields = if ($argText) { ConvertTo-Fields $argText } else { @() }
|
|
$argsRef = '{}'
|
|
if ($fields.Count -gt 0) {
|
|
$out.Add("const Game::Doc::Field ${sym}Args[] = {")
|
|
$fields | ForEach-Object { $out.Add($_) }
|
|
$out.Add('};')
|
|
$argsRef = "${sym}Args"
|
|
}
|
|
$out.Add("const Game::Doc::Field ${sym}Rets[] = {")
|
|
$out.Add(' // TODO: one entry per pushed value, in order.')
|
|
$out.Add(' Game::Doc::Req("TODO", "TODO"),')
|
|
$out.Add('};')
|
|
$sysArg = if ($system) { ", `"$system`"" } else { '' }
|
|
$out.Add("const Game::Doc::Function $sym{")
|
|
$out.Add(" `"$summary`",")
|
|
$out.Add(" $argsRef, ${sym}Rets$sysArg};")
|
|
$out.Add('')
|
|
}
|
|
|
|
foreach ($m in $globals) { & $emit $m.Groups[1].Value 'TODOGlobals' }
|
|
foreach ($m in $glue) { & $emit $m.Groups[1].Value 'TODOGlobals' }
|
|
foreach ($m in $tables) { & $emit "$($m.Groups[1].Value).$($m.Groups[2].Value)" $null }
|
|
|
|
$dest = Join-Path $OutDir ($rel -replace '^src/', '')
|
|
$dest = [IO.Path]::ChangeExtension($dest, $null) + 'skel.cpp'
|
|
$destDir = Split-Path -Parent $dest
|
|
if (-not (Test-Path $destDir)) { New-Item -ItemType Directory -Force $destDir | Out-Null }
|
|
$noBom = New-Object System.Text.UTF8Encoding($false)
|
|
[IO.File]::WriteAllText($dest, ($out -join "`r`n") + "`r`n", $noBom)
|
|
$written++
|
|
Write-Host " $rel -> $dest"
|
|
}
|
|
|
|
Write-Host ""
|
|
Write-Host "$written skeleton file(s) written to $OutDir."
|
|
Write-Host "Nothing under src/ was modified."
|