From db84f0ff4f9787b3fd496015b584c49b789d037e Mon Sep 17 00:00:00 2001 From: Rhys van der Waerden Date: Thu, 6 Feb 2025 02:04:58 +1100 Subject: [PATCH] Convert LDoc to lua-language-server (#1775) * Automatic update from ldoc -> lls syntax Using a set of simple regexp replacements to convert from LDoc compatible lua doc syntax. Script used: https://github.com/rhys-vdw/spring-lua-doc-converter * LuaBitOps.cpp: Update Lua docs * LuaConstCOB.cpp: Update Lua docs * LuaConstCMD.cpp: Update Lua docs * LuaConstCMDTYPE.cpp: Update Lua docs * LuaConstGL.cpp: Update Lua docs * LuaConstGame.cpp: Update Lua docs * LuaConstPlatform.cpp: Update Lua docs * LuaConstGL.cpp: Define GLenum in Lua * LuaFBOs.cpp: Update Lua docs * LuaHandle.cpp: Update Lua docs * LuaHandleSynced.cpp: Update Lua docs * Lua docs: cmdOpts -> CommandOptions * Lua docs: mods -> KeyModifiers * LuaMathExtra.cpp: Update Lua docs * LuaMenu.cpp: Update Lua docs * LuaMetalMap.cpp: Update Lua docs * LuaOpenGL.cpp: Update Lua docs * LuaRBOs.cpp: Update Lua docs * LuaShaders.cpp: Update Lua docs * LuaSyncedCtrl.cpp: Update Lua docs * LuaVBO.cpp: Update Lua docs * Create Types.lua To contain type definitions shared between the various cpp lua files * LuaUnsyncedRead.cpp: Update Lua docs And move some more definitions into `Types.lua` * LuaVAO.cpp, LuaVAOImpl.cpp: Update Lua docs * LuaVBO.cpp, LuaVBOImpl.cpp: Update Lua docs * LuaIntro.cpp: Update Lua docs * Fix typo * Lua: GLenum -> GL * Better Lua types * Move resource types into Types.lua * Add .luarc.json * Create Lua regeneration script To be replace with github action * Regenerate Lua library * Add GitHub workflow to regenerate Lua metafiles * Remove Lua script * FIX .luarc.json * Lua library action updates submodule * Set git config globally * Update lua-api.md Written by badosu * Add guide for generating LuaLS docs * Update site README with specific Ruby version * Remove params from generated Lua API methods * Update Gemfile * Use correct LLS doc filename * WIP Messing with .luarc.json * Add ignores to luarc * lua-api.md improvements Fixing a bunch of bad stuff. * Add syntax highlighting on doc "view" * Update docs README Change the command to generate from root, because of a bug where using relative paths causes duplicated generation. * Show the definition for alias types * Remove double hr in API docs * Add guide for installing lua-doc-extractor * Remove use of external Lua library repo * Add LUA_DOC_GUIDE * Generate docs using Lua Language Server * Update LuaTracyExtra.cpp * Update LuaTableExtra * Update LuaLS library * Allow publishing site from other branches For testing * Remove LDoc config * Revert "Remove use of external Lua library repo" This reverts commit 81874c2d08adeab3577e42b0c7dc9fce0d3dd0d2. * Remove disabled libs from main luarc * Do not push generated lua library to Recoil repo * Delete generated Lua library * Update LuaFonts LDoc -> LLS * LDoc -> LLS * More LDoc -> LLS cleanup * Fix some stuff after rebase * Add recoil-lua-library submodule * Keep the local lua library updated * Add Facing alias * Init submodule before updating * Update Lua libary submodule * Update Lua doc guide * Move Lua guide into site guides * Update site readme for lua language server * Init library submodule before generating API docs * Prefer SSH key lua library deployment * Update Lua libary submodule * Point workflow to beyond-all-reason/recoil-lua-library * Update submodule to beyond-all-reason/recoil-lua-library * Update doc link to beyond-all-reason/recoil-lua-library * Remove LDoc from gitignore * Install lua-doc-extractor from npm * Add comment to .luarc.doc.json * Ignore lua-language-server doc export * Add header to lua-language-server guide * Add section on IDE support for Lua * Fix manual Lua doc export steps * Ignore .bundle in site folder Contains local bundle config * Add note about bad docs to Lua API page * Install lua-doc-extractor globally * Remove recoil-lua-library submodule * Do not add .luarc.json to library repo * Fix typo in lua-language-server doc gen command * Remove doc/site/ldoc folder * Prefer rgb type * Clean up lua doc for SetHeightMap * lua-api.markdown: Show ... varargs param properly * Remove TOC from lua-api.md * Fix ActiveCommandChanged params * Add source link to recoil-lua-library * Open source links in new tab * Remove type from API heading * Remove meta comment from losAccess doc * Fix workflow link * Fix library path * Add author to lls guide * Add changelog entry * Remove required arguments from `math.bit_*` * Revert "Add changelog entry" This reverts commit f79ebc39e9c32b6309d565b6477f8e8dd392491a. * Fix up some docs in LuaUnsyncedCtrl.cpp * Prefer integer type for ID params * Add more detailed lua language support changelog * Remove engine dev notes from changelog * Split LLS docs into two engine and game dev articles --------- Co-authored-by: rhys-vdw Co-authored-by: rhys-vdw <822105+rhys-vdw@users.noreply.github.com> --- .github/workflows/generate-lua-library.yml | 55 + .github/workflows/publish-site.yml | 35 +- .gitignore | 12 +- doc/LDoc/README.md | 3 - doc/LDoc/config.ld | 45 - doc/LDoc/ldoc.ltp | 229 -- doc/site/.gitignore | 1 + doc/site/Gemfile.lock | 2 +- doc/site/README.md | 14 +- doc/site/_authors/rhys-vdw.markdown | 4 + .../changelogs/running-changelog.markdown | 10 + doc/site/development/documenting-lua.markdown | 215 ++ doc/site/guides/lua-language-server.markdown | 19 + doc/site/ldoc/.gitkeep | 0 doc/site/lua-api.md | 112 +- rts/Lua/LuaBitOps.cpp | 33 +- rts/Lua/LuaConstCMD.cpp | 127 +- rts/Lua/LuaConstCMDTYPE.cpp | 35 +- rts/Lua/LuaConstCOB.cpp | 250 ++- rts/Lua/LuaConstEngine.cpp | 30 +- rts/Lua/LuaConstGL.cpp | 342 +-- rts/Lua/LuaConstGame.cpp | 111 +- rts/Lua/LuaConstPlatform.cpp | 53 +- rts/Lua/LuaFBOs.cpp | 125 +- rts/Lua/LuaFonts.cpp | 7 +- rts/Lua/LuaHandle.cpp | 664 +++--- rts/Lua/LuaHandleSynced.cpp | 411 ++-- rts/Lua/LuaIntro.cpp | 9 +- rts/Lua/LuaMathExtra.cpp | 75 +- rts/Lua/LuaMenu.cpp | 7 +- rts/Lua/LuaMetalMap.cpp | 11 +- rts/Lua/LuaOpenGL.cpp | 36 +- rts/Lua/LuaRBOs.cpp | 34 +- rts/Lua/LuaRules.cpp | 1 - rts/Lua/LuaShaders.cpp | 258 ++- rts/Lua/LuaSyncedCtrl.cpp | 1982 ++++++++--------- rts/Lua/LuaSyncedMoveCtrl.cpp | 1 - rts/Lua/LuaSyncedRead.cpp | 1878 ++++++++-------- rts/Lua/LuaTableExtra.cpp | 10 +- rts/Lua/LuaTracyExtra.cpp | 27 +- rts/Lua/LuaUnsyncedCtrl.cpp | 1445 ++++++------ rts/Lua/LuaUnsyncedRead.cpp | 1128 +++++----- rts/Lua/LuaUtils.cpp | 15 + rts/Lua/LuaVAO.cpp | 12 +- rts/Lua/LuaVAOImpl.cpp | 72 +- rts/Lua/LuaVBO.cpp | 38 +- rts/Lua/LuaVBOImpl.cpp | 262 ++- rts/Lua/LuaVFS.cpp | 1 - rts/Lua/LuaZip.cpp | 1 - rts/Lua/library/.luarc.json | 41 + rts/Lua/library/Types.lua | 120 + 51 files changed, 5413 insertions(+), 4995 deletions(-) create mode 100644 .github/workflows/generate-lua-library.yml delete mode 100644 doc/LDoc/README.md delete mode 100644 doc/LDoc/config.ld delete mode 100644 doc/LDoc/ldoc.ltp create mode 100644 doc/site/_authors/rhys-vdw.markdown create mode 100644 doc/site/development/documenting-lua.markdown create mode 100644 doc/site/guides/lua-language-server.markdown delete mode 100644 doc/site/ldoc/.gitkeep create mode 100644 rts/Lua/library/.luarc.json create mode 100644 rts/Lua/library/Types.lua diff --git a/.github/workflows/generate-lua-library.yml b/.github/workflows/generate-lua-library.yml new file mode 100644 index 0000000000..91091af6f7 --- /dev/null +++ b/.github/workflows/generate-lua-library.yml @@ -0,0 +1,55 @@ +name: Generate Lua library +on: + workflow_dispatch: + push: + branches: + - master + paths: + - 'rts/Lua/**' +jobs: + generate-library: + name: Regenerate library + runs-on: ubuntu-latest + steps: + - name: Configure git + run: | + git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" + git config --global user.name "github-actions[bot]" + + - name: Checkout Lua CPP files + uses: actions/checkout@v4 + with: + sparse-checkout: rts/Lua + path: recoil + + # NOTE: This step is duplicated in `publish-site.yml` + - name: Generate Lua library + working-directory: recoil/rts/Lua/ + run: | + npm install -g lua-doc-extractor + lua-doc-extractor *.cpp --dest library/generated + + - name: Check out library repo + uses: actions/checkout@v4 + with: + repository: beyond-all-reason/recoil-lua-library + ssh-key: ${{ secrets.RECOIL_LUA_LIBRARY_SSH_KEY }} + path: library + + - name: Copy changes into library repo + run: | + rm -rf library/library + cp -r recoil/rts/Lua/library library + # Remove .luarc.json (this is only required for doc gen) + rm library/library/.luarc.json + + # Always try to update library repo (even if generation did not make changes). + # Hand-written files may have changed without generated output changing, + # and library may simply be out of date for whatever reason. + - name: Commit and push library repo + uses: stefanzweifel/git-auto-commit-action@v5 + with: + repository: ./library + commit_message: | + Update library + Generated from https://github.com/${{ github.repository }}/commit/${{ github.sha }} \ No newline at end of file diff --git a/.github/workflows/publish-site.yml b/.github/workflows/publish-site.yml index c714c852f7..a7eda3dd27 100644 --- a/.github/workflows/publish-site.yml +++ b/.github/workflows/publish-site.yml @@ -13,22 +13,37 @@ jobs: - name: Install Dependencies run: | sudo apt-get update -y - sudo apt-get install --fix-missing -y lua-ldoc lua-markdown jq p7zip-full libsdl2-2.0-0 libopenal1 + sudo apt-get install --fix-missing -y jq p7zip-full libsdl2-2.0-0 libopenal1 + - name: Set up Homebrew + id: set-up-homebrew + uses: Homebrew/actions/setup-homebrew@master + - name: Install Lua Language Server + run: | + brew install lua-language-server - name: Checkout Source Repository uses: actions/checkout@v2 - with: - ref: master - name: Generate Dynamic Content run: | bash doc/site/_scripts/get_release_data.sh bash doc/site/_scripts/get_engine_data.sh git add -f doc/site/_data - - name: Run LDoc + # NOTE: This step is duplicated in `generate-lua-library.yml` + - name: Generate Lua library + working-directory: rts/Lua/ + run: | + npm install -g lua-doc-extractor + lua-doc-extractor *.cpp --dest library/generated + # NOTE: Running LLS 3.13.4 from a subdirectory with a relative path seems + # to cause duplicate class fields to be generated. Presumably a bug in + # LLS. + - name: Export Lua data using Lua Language Server + run: | + lua-language-server --doc rts/Lua/library --doc_out_path doc/site/_data + git add -f doc/site/_data + - name: Commit changes run: | - ldoc -c doc/LDoc/config.ld . - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git config user.name "github-actions[bot]" - git add -f doc/site/ldoc + git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" + git config --global user.name "github-actions[bot]" git commit -m "Update doc/site" - name: Check if gh-pages exists id: check-ghpages @@ -39,8 +54,8 @@ jobs: id: site-changes if: steps.check-ghpages.outputs.exists == 'true' run: | - git diff --stat origin/gh-pages master:doc/site - git diff --quiet origin/gh-pages master:doc/site && (echo "modified=false" > $GITHUB_OUTPUT) || (echo "modified=true" > $GITHUB_OUTPUT) + git diff --stat origin/gh-pages ${{ github.ref_name }}:doc/site + git diff --quiet origin/gh-pages ${{ github.ref_name }}:doc/site && (echo "modified=false" > $GITHUB_OUTPUT) || (echo "modified=true" > $GITHUB_OUTPUT) - name: Push gh-pages # Only push gh-pages if doc/site/ was changed or ldoc did changes if: steps.check-ghpages.outputs.exists == 'false' || steps.site-changes.outputs.modified == 'true' run: | diff --git a/.gitignore b/.gitignore index c4f1cd3156..d5febfec9c 100644 --- a/.gitignore +++ b/.gitignore @@ -153,7 +153,7 @@ x64/ *.sln *.db Spring.VC.VC.opendb -/out/build/** +/out/build/** # downloaded files /pool @@ -161,11 +161,15 @@ Spring.VC.VC.opendb /rapid /packages -# ignore autogenerated doc -/doc/site/ldoc - # ignore local development paths .cache toolchain compile_commands.json build-* + +# Lua Language Server doc output +/doc/site/_data/doc.json +/doc/site/_data/doc.md + +# lua-doc-extractor generated library +/rts/Lua/library/generated \ No newline at end of file diff --git a/doc/LDoc/README.md b/doc/LDoc/README.md deleted file mode 100644 index 9793c25b14..0000000000 --- a/doc/LDoc/README.md +++ /dev/null @@ -1,3 +0,0 @@ -Install LDoc for your operating system or from LuaRocks - -Inside `doc/LDoc` run `ldoc .`. diff --git a/doc/LDoc/config.ld b/doc/LDoc/config.ld deleted file mode 100644 index 89375c9e27..0000000000 --- a/doc/LDoc/config.ld +++ /dev/null @@ -1,45 +0,0 @@ -project='Spring Lua API' -title='Spring Lua API documentation' -description='A Lua documentation tool' -not_luadoc=true -no_space_before_args=true -format='markdown' -file={ - '../../rts/Lua/LuaSyncedCtrl.cpp', - '../../rts/Lua/LuaUnsyncedCtrl.cpp', - '../../rts/Lua/LuaSyncedRead.cpp', - '../../rts/Lua/LuaUnsyncedRead.cpp', - '../../rts/Lua/LuaSyncedMoveCtrl.cpp', - '../../rts/Lua/LuaHandle.cpp', - '../../rts/Lua/LuaHandleSynced.cpp', - '../../rts/Lua/LuaVFS.cpp', - '../../rts/Lua/LuaVAO.cpp', - '../../rts/Lua/LuaVAOImpl.cpp', - '../../rts/Lua/LuaVBO.cpp', - '../../rts/Lua/LuaVBOImpl.cpp', - '../../rts/Lua/LuaOpenGL.cpp', - '../../rts/Lua/LuaZip.cpp', - '../../rts/Lua/LuaRules.cpp', - '../../rts/Lua/LuaMetalMap.cpp', - '../../rts/Lua/LuaShaders.cpp', - '../../rts/Lua/LuaFBOs.cpp', - '../../rts/Lua/LuaRBOs.cpp', - '../../rts/Lua/LuaMathExtra.cpp', - '../../rts/Lua/LuaBitOps.cpp', - '../../rts/Lua/LuaConstGame.cpp', - '../../rts/Lua/LuaConstEngine.cpp', - '../../rts/Lua/LuaConstPlatform.cpp', - '../../rts/Lua/LuaConstCMD.cpp', - '../../rts/Lua/LuaConstCMDTYPE.cpp', - '../../rts/Lua/LuaConstCOB.cpp', - '../../rts/Lua/LuaConstGL.cpp', -} -dir='../site/ldoc' -template='./' - -local repoPath = "https://github.com/beyond-all-reason/spring/blob/BAR105/%s" - -custom_see_handler('^(rts/.*)$', function(filename) - local url = repoPath:format(filename) - return filename, url -end) diff --git a/doc/LDoc/ldoc.ltp b/doc/LDoc/ldoc.ltp deleted file mode 100644 index 7750febb22..0000000000 --- a/doc/LDoc/ldoc.ltp +++ /dev/null @@ -1,229 +0,0 @@ -# local localurl = module and module.name and ldoc.ref_to_module(module) or ("../" .. ldoc.output .. ".html") -# localurl = localurl:gsub("%.%./", "ldoc/") -# modname = module and module.name or "Home" -# local function M(txt,item) return ldoc.markup(txt,item,ldoc.plain) end ---- -layout: default -title: $(modname) -permalink: $(localurl) -description: $(module and M(module.summary,module) or "") -parent: Lua API -# -- do not publish if index page -$(module or "published: false") ---- - -{% raw %} -# local no_spaces = ldoc.no_spaces -# local display_name = ldoc.display_name -# local iter = ldoc.modules.iter -# local nowrap = ldoc.wrap and '' or 'nowrap' -# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries - $(ldoc.body) -# elseif module then -- module documentation -

$(ldoc.module_typename(module)) $(module.name)

-

$(M(module.summary,module))

-

$(M(module.description,module))

-# if module.tags.include then - $(M(ldoc.include_file(module.tags.include))) -# end -# if module.see then -

See also:

- -# end -- if see -# if module.usage then -

Usage:

- -# end -- if usage -# if module.info then -

Info:

- -# end -- if module.info - -# if not ldoc.no_summary then -# -- bang out the tables of item types for this module (e.g Functions, Tables, etc) -# for kind,items in module.kinds() do -

$(kind)

-
-# for item in items() do -
- $(item.name) -
-
- $(M(item.summary,item)) -
-# end -- for items -
-# end -- for kinds -# end -- if not no_summary - -# --- currently works for both Functions and Tables. The params field either contains -# --- function parameters or table fields. -# local show_return = not ldoc.no_return_or_parms -# local show_parms = show_return -# for kind, items in module.kinds() do -# local kitem = module.kinds:get_item(kind) -# local has_description = kitem and ldoc.descript(kitem) ~= "" -

- $(kind) -

- $(M(module.kinds:get_section_description(kind),nil)) -# if kitem then -# if has_description then -

$(M(ldoc.descript(kitem),kitem))

-# end -# if kitem.usage then -

Usage:

- 
$(ldoc.prettify(kitem.usage[1]))
-# end -# end -# for item in items() do -

-# if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then - line $(item.lineno) -# end - $(display_name(item)) -

-

$(item.summary)

-
-

- $(item.description) -

- -# if ldoc.custom_tags then -# for custom in iter(ldoc.custom_tags) do -# local tag = item.tags[custom[1]] -# if tag and not custom.hidden then -

$(custom.title or custom[1]):

-
    -# for value in iter(tag) do -
  • $(custom.format and custom.format(value) or M(value))
    • -# end -- for -# end -- if tag -
-# end -- iter tags -# end - -# if show_parms and item.params and#item.params > 0 then -# local subnames = module.kinds:type_of(item).subnames -# if subnames then -

$(subnames):

-# end -
    -# for parm in iter(item.params) do -# local param,sublist = item:subparam(parm) -# if sublist then -
  1. $(sublist)$(M(item.params.map[sublist],item)) -
      -# end -# for p in iter(param) do -# local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p) -
    • - $(name) -# if tp ~= '' then - $(tp) -# end - $(M(item.params.map[p],item)) -# if def == true then - (optional) -# elseif def then - (default $(def)) -# end -# if item:readonly(p) then - readonly -# end -
      • -# end -# if sublist then -
    -# end -# end -- for -
-# end -- if params - -# if show_return and item.retgroups then local groups = item.retgroups -

Returns:

-# for i,group in ldoc.ipairs(groups) do -
    -# for r in group:iter() do local type, ctypes = item:return_type(r); local rt = ldoc.typename(type) -
  1. -# if rt ~= '' then - $(rt) -# end - $(M(r.text,item))
    2. -# if ctypes then -
      -# for c in ctypes:iter() do -
    • $(c.name) - $(ldoc.typename(c.type)) - $(M(c.comment,item))
      • -# end -
    -# end -- if ctypes -# end -- for r -
-# if i <#groups then -

Or

-# end -# end -- for group -# end -- if returns - -# if show_return and item.raise then -

Raises:

- $(M(item.raise,item)) -# end - -# if item.see then -

See also:

-
    -# for see in iter(item.see) do -
  • $(see.label)
    • -# end -- for -
-# end -- if see - -# if item.usage then -

Usage:

-
    -# for usage in iter(item.usage) do - 
  • $(ldoc.prettify(usage))
    • -# end -- for -
-# end -- if usage -
-# end -- for items -# end -- for kinds - -# else -- if module; project-level contents -# if ldoc.description then -

$(M(ldoc.description,nil))

-# end -# if ldoc.full_description then -

$(M(ldoc.full_description,nil))

-# end - -# for kind, mods in ldoc.kinds() do -

$(kind)

-# kind = kind:lower() - -# for m in mods() do - - - - -# end -- for modules -
$(m.name)$(M(ldoc.strip_header(m.summary),m))
-# end -- for kinds -# end -- if module -{% endraw %} diff --git a/doc/site/.gitignore b/doc/site/.gitignore index f40fbd8ba5..85b64b4e58 100644 --- a/doc/site/.gitignore +++ b/doc/site/.gitignore @@ -2,4 +2,5 @@ _site .sass-cache .jekyll-cache .jekyll-metadata +.bundle vendor diff --git a/doc/site/Gemfile.lock b/doc/site/Gemfile.lock index f78bcafe66..186b67be4b 100644 --- a/doc/site/Gemfile.lock +++ b/doc/site/Gemfile.lock @@ -219,7 +219,7 @@ GEM jekyll-feed (~> 0.9) jekyll-seo-tag (~> 2.1) minitest (5.17.0) - nokogiri (1.14.2-x86_64-linux) + nokogiri (1.17.2-x86_64-linux) racc (~> 1.4) octokit (4.25.1) faraday (>= 1, < 3) diff --git a/doc/site/README.md b/doc/site/README.md index 2fa9462992..51016c9434 100644 --- a/doc/site/README.md +++ b/doc/site/README.md @@ -4,7 +4,9 @@ The recoil site is a jekyll application, usually hosted on github pages. ## Testing locally -Have a reasonably recent version of Ruby. Inside `doc/site` run: +Install Ruby 3.2.3 ([newer versions can cause problems](https://stackoverflow.com/a/77896791/317135)). + +Inside `doc/site` run: ```bash bundle @@ -13,14 +15,12 @@ bundle exec jekyll build && bundle exec jekyll serve Navigate to http://localhost:4000/spring -## Generating LDoc - -Have [LDoc](https://github.com/lunarmodules/LDoc) installed or available at your `$PATH`. +## Generating Lua API -Inside `doc/LDoc` run: +Have [Lua Language Server](https://luals.github.io/) and [lua-doc-extractor](https://github.com/rhys-vdw/lua-doc-extractor) installed and available in `$PATH`. ```bash -ldoc -c config.ld . +lua-doc-extractor rts/Lua/*.cpp --dest rts/Lua/library/generated && lua-language-server --doc rts/Lua/library --doc_out_path doc/site/_data ``` -Keep in mind to see changes on the site you might have to restart jekyll. +See [Documenting Lua development guide](development/documenting-lua.markdown) for more info. \ No newline at end of file diff --git a/doc/site/_authors/rhys-vdw.markdown b/doc/site/_authors/rhys-vdw.markdown new file mode 100644 index 0000000000..c0797969e6 --- /dev/null +++ b/doc/site/_authors/rhys-vdw.markdown @@ -0,0 +1,4 @@ +--- +short_name: rhys-vdw +github: rhys-vdw +--- diff --git a/doc/site/changelogs/running-changelog.markdown b/doc/site/changelogs/running-changelog.markdown index d6fa95f3be..03cdea10cd 100644 --- a/doc/site/changelogs/running-changelog.markdown +++ b/doc/site/changelogs/running-changelog.markdown @@ -94,6 +94,16 @@ So far contains three vars: More will be added in the future as new features are added. +### Lua language server support + +LDoc has been replaced by [Lua Language Server](https://luals.github.io/) compatible annotations. This allows for language server support when editing Lua code (namely autocompletion and type checking). + +Type definitions can be found in the [Lua library repo](https://github.com/beyond-all-reason/recoil-lua-library). This is intended to be included as a submodule in projects that use the engine. + +[Lua API docs]({{ site.baseurl }}{% link lua-api.md %}) are now generated from LLS definitions instead of LDoc. This has caused a regression in docs quality, with all docs on a single page and some docs missing information. Improvements to the docs are being considered. + +For more information see the [Lua Language Server guide]({{ site.baseurl }}{% link guides/lua-language-server.markdown %}). + ### Death events * `wupget:UnitDestroyed` will pass the builder as the killer if a unit gets reclaimed. Note that reclaim still does not generate `UnitDamaged` events. diff --git a/doc/site/development/documenting-lua.markdown b/doc/site/development/documenting-lua.markdown new file mode 100644 index 0000000000..a4203a9c51 --- /dev/null +++ b/doc/site/development/documenting-lua.markdown @@ -0,0 +1,215 @@ +--- +layout: default +title: Documenting Lua +parent: Development +permalink: development/documenting-lua +author: rhys-vdw +--- + +{: .note } +> This article covers working with Lua for **engine developers**. For adding the library to your Recoil game, refer to the [Lua Language Server guide]({{ site.baseurl }}{% link guides/lua-language-server.markdown %}). + +# Documenting Lua + +The Lua library is a collection of type definitions that can be included in Recoil games to provide intellisense and type checking. It is found in the [recoil-lua-library](https://github.com/beyond-all-reason/recoil-lua-library) repo. + +The library is generated from doc comments within the project. + +## Generating the library + +### Automatic library generation + +The library is generated by the [Generate Lua library workflow](https://github.com/beyond-all-reason/spring/tree/master/.github/workflows/generate-lua-library.yml). This workflow runs automatically every time a PR is merged. + +### Manually generating the library + +To test library generation, you can run [lua-doc-extractor](https://github.com/rhys-vdw/lua-doc-extractor) locally. + +Install lua-doc-extractor: + +```bash +npm install -g lua-doc-extractor +``` + +At root, run: + +```bash +# First delete any previously generated output. +rm -rf rts/Lua/library/generated + +# Regenerate the library. +lua-doc-extractor rts/Lua/*.cpp --dest rts/Lua/library/generated +``` + +## Doc comments + +### Doc comments within CPP files + +Special comments blocks are parsed by [lua-doc-extractor](https://github.com/rhys-vdw/lua-doc-extractor) and converted into [definition files](https://luals.github.io/wiki/definition-files/). + +Comment blocks must start with `/***`, and by convention each line starts with `*`. + +```cpp +/*** + * @function Spring.GetFeaturesInScreenRectangle + * + * Get features inside a rectangle area on the map + * + * @param left number + * @param top number + * @param right number + * @param bottom number + * @return nil|number[] featureIDs + */ +int LuaUnsyncedRead::GetFeaturesInScreenRectangle(lua_State* L) +{ + // CPP code +} +``` + +These comments are mostly copied directly into the Lua library, but some code generation is required. For these [custom tags](https://github.com/rhys-vdw/lua-doc-extractor?tab=readme-ov-file#custom-tags) must be used. + +Markdown is supported in all text. + +### Authored library files + +Hand-authored library files exist in `/rts/Lua/Library/`. These are appropriate to use when a Lua type is used in multiple CPP files. + +All files under `/rts/Lua/Library/` are directly copied into the library when the workflow runs. + +## Annotations + +[Full list of annotations](https://luals.github.io/wiki/annotations/). + +### Common annotations + +- [`@function`](https://github.com/rhys-vdw/lua-doc-extractor?tab=readme-ov-file#function-name) +- [`@table`](https://github.com/rhys-vdw/lua-doc-extractor?tab=readme-ov-file#table-name) +- [`@param`](https://luals.github.io/wiki/annotations/#param) +- [`@return`](https://luals.github.io/wiki/annotations/#return) +- [`@field`](https://luals.github.io/wiki/annotations/#field) + +### Types + +[List of types](https://luals.github.io/wiki/annotations/#documenting-types) + +#### Common types + +- `integer` +- `nil` +- `any` +- `boolean` +- `string` +- `number` (for floating point numbers) +- `integer` +- `table<,>` + + +{: .note } +> Literals (e.g. `true`, `false`, `5`) are also available as types. `true` is useful in the case where a table is being used as a set, e.g. +> ``` +> table +> ``` + +#### Unions + +Union types can be specified with `|`. + +``` +string|boolean|number +``` + +Suffix with `?` as a shorthand for a union with `nil`, e.g. `string?` is equivalent to `string|nil`. + +#### Arrays + +An array type is expressed as `type[]`. + +- `number[]` — Array of numbers. +- `string?[]` — Array of string or null. +- `number|string[]` — A single number, or an array of strings. +- `(number|string)[]` — An array with a mix of number and string. + +## Examples + +### Function + +- Must start with `@function TableName.FunctionName`. +- Can have any amount of description. This should be added after the first +- Specify parameters with `@param parameterName type Description...` +- Specify return type with `@return type name Description...` +- For multiple returns use one per line. + +{: .warning } +> `@return` must specify the type _before_ the name, whereas `@param` takes the name before the type. + +```cpp +/*** + * @function Math.Add + * + * Add two integers together. + * + * This function will add two numbers together and return the result. + * + * ```lua + * local totalHeight = Math.Add(legLength, upperBodyHeight) + * ``` + * + * @param a integer The first number. + * @param b integer The second number. + * @returns integer result The sum of `a` and `b`. + */ +``` + +### Class + +Structured data is expressed as a class. This represents a table with expected key/value pairs. + +- Must start with `@class ClassName`. This name becomes a type that can be used in annotations. +- Fields are specified by `@field fieldName type Description...`. + +```cpp +/*** + * @class Color + * + * Describes an RGB color value. + * + * @field red number The red value. + * @field green number The green value. + * @field blue number The blue value. + */ + +/*** + * @function ColorUtility.LerpColor + * @param from Color + * @param to Color + * @param value number The mix (in range `[0,1]`) of colors to combine. `1` will return `to` and `0` will return `from`. + * @return Color color + */ +``` + +### Table + +A global table can be defined like so: + +```cpp +/*** + * @table Spring + */ +``` + +This will define a table. This table can then be referenced in a function name e.g. `@function Spring.MyFunction`. + +A table of constants can also be expressed using `@field`: + +```cpp +/*** + * @table CoolNumbers + * @field number Pi + * @field integer SixyNine + * @field integer FourTwenty + */ +``` + +{: .note } +> A table is a global that can be accessed in Lua and not a type like `@class`. \ No newline at end of file diff --git a/doc/site/guides/lua-language-server.markdown b/doc/site/guides/lua-language-server.markdown new file mode 100644 index 0000000000..f2a5812ca2 --- /dev/null +++ b/doc/site/guides/lua-language-server.markdown @@ -0,0 +1,19 @@ +--- +layout: default +title: Lua Language Server +parent: Guides +permalink: guides/lua-language-server +author: rhys-vdw +--- + +# Lua Language Server + +Recoil now provides a Lua library that is compatible with [Lua Language Server](https://luals.github.io/), providing type checking and intellisense in your IDE. + +### Adding the library to your project + +The [recoil-lua-library](https://github.com/beyond-all-reason/recoil-lua-library) package provides type definitions for your editor. This can be added as a submodule to your project (following its usage guide). + +### IDE support + +When working with Lua, we recommend using [Visual Studio Code](https://code.visualstudio.com/) with the [lua-language-server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) plugin. See the [Lua Language Server website](https://luals.github.io/#install) for other supported editors. \ No newline at end of file diff --git a/doc/site/ldoc/.gitkeep b/doc/site/ldoc/.gitkeep deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/doc/site/lua-api.md b/doc/site/lua-api.md index bf947310d8..23d99268e0 100644 --- a/doc/site/lua-api.md +++ b/doc/site/lua-api.md @@ -8,13 +8,109 @@ permalink: lua-api --- # Lua API -
-{% for pagey in site.pages %} -{% if pagey.parent == 'Lua API' %} -
-{{ pagey.title }} -
-
{{ pagey.description }}
+ +{: .note } +> We have recently moved to [Lua Language Server](https://luals.github.io/) for Lua support in IDE. This documentation is generated from its doc export function, which is quite limited. Currently all docs are inluded on a single page, and some information is missing. +> +> In cases where docs seem incomplete (e.g. `table` and `enum` definitions), try the "source" link to see if there is more information. +> +> See the [Lua Language Server guide](guides/lua-language-server.markdown) for more information. + +{% for row in site.data.doc %} + +{% assign defines = row["defines"][0] %} + +{% comment %} + Determine the type of the item. This is complicated by functions being defined + as `variables` which are extending a function. +{% endcomment %} + +{% assign type = row.type %} +{% if type == "variable" %} + {% assign type = defines.extends.type %} +{% endif %} + +--- + +{% comment %} + --- Header --- + + Render the name of item, including its type. + Then render the first line of its "view" - the raw code definition. This will + show the full function signature without its return values (which are on + subsequent lines). +{% endcomment %} + +## {{row["name"]}} +{{type}} +{% if defines.type == 'doc.class' %} + {% comment %} Do nothing, classes just have their name as the view. {% endcomment %} +{% elsif row.type != 'variable' and defines.view %} +```lua +{{ defines.view | newline_to_br | strip_newlines | split: '
' | first }} +``` +{% elsif defines.extends.view %} +```lua +{{ defines.extends.view | newline_to_br | strip_newlines | split: '
' | first }} +``` +{% endif %} + +{% if defines.file != empty %} + \[source\] +{% endif %} + +{% comment %} + --- Description --- + + `defines.extends.rawdesc` seems to have the description without inlined doc + tags. However it is not always available. +{% endcomment %} + +{% if defines.extends %} +{{ defines.extends.rawdesc }} +{% else %} +{{ defines.desc }} +{% endif %} + +{% if row.fields and row.fields != empty %} +### Fields + + +{% for field in row.fields %} +- {{ field.name }} `{{ field.extends.view }}` {% if field.rawdesc %} — {{field.rawdesc}} {% endif %} +{% endfor %} + {% endif %} + + +{% if defines["extends"] %} +{% assign extends = defines["extends"] %} + +{% if extends["args"] and extends["args"] != empty %} +## Params + + +{% for arg in extends.args %} + {% comment %} Support varargs syntax, which has type "..." and no name {% endcomment %} + {% if arg.type == "..." %} + {% assign name = arg.type %} + {% else %} + {% assign name = arg.name %} + {% endif %} +1. {{ name }} `{{ arg.view }}` {% if arg.desc %} — {{ arg.desc }} {% endif %} {% endfor %} -
+ +{% endif %} + +{% if extends["returns"] and extends["returns"] != empty %} + +### Returns + +{% for return in extends["returns"] %} +1. `{{ return["view"] }}` {{return["name"]}} {% if return["rawdesc"] %} — {{return["rawdesc"]}} {% endif %} +{% endfor %} +{% endif %} + +{% endif %} + +{% endfor %} \ No newline at end of file diff --git a/rts/Lua/LuaBitOps.cpp b/rts/Lua/LuaBitOps.cpp index 5b2a91598b..08197c547a 100644 --- a/rts/Lua/LuaBitOps.cpp +++ b/rts/Lua/LuaBitOps.cpp @@ -16,7 +16,6 @@ const int mask = 0x00FFFFFF; // 2^24 /****************************************************************************** * math bit extensions - * @module BitOps * * Note: there are no bit shift. Use those Lua functions instead for 24 bits bitshift * 24 bits because only the 24 bits of the mantissa can be easily used in a 32 bit float @@ -58,11 +57,8 @@ static inline unsigned int luaL_checkuint(lua_State* L, int index) /*** Returns the bitwise OR of all arguments. Only use up to 24 bit integers. * * @function math.bit_or - * @number a1 - * @number a2 - * @number[opt] a3 - * @number[opt] an - * @treturn number i + * @param ... integer + * @return integer result */ int LuaBitOps::bit_or(lua_State* L) { @@ -78,11 +74,8 @@ int LuaBitOps::bit_or(lua_State* L) /*** Returns the bitwise AND of all arguments. Only use up to 24 bit integers. * * @function math.bit_and - * @number a1 - * @number a2 - * @number[opt] a3 - * @number[opt] an - * @treturn number i + * @param ... integer + * @return integer result */ int LuaBitOps::bit_and(lua_State* L) { @@ -98,11 +91,8 @@ int LuaBitOps::bit_and(lua_State* L) /*** Returns the bitwise XOR of all arguments. Only use up to 24 bit integers. * * @function math.bit_xor - * @number a1 - * @number a2 - * @number[opt] a3 - * @number[opt] an - * @treturn number i + * @param ... integer + * @return integer result */ int LuaBitOps::bit_xor(lua_State* L) { @@ -118,8 +108,8 @@ int LuaBitOps::bit_xor(lua_State* L) /*** Returns the bitwise NOT of the 24 bit integer argument. * * @function math.bit_inv - * @number a1 - * @treturn number i + * @param value integer + * @return integer result */ int LuaBitOps::bit_inv(lua_State* L) { @@ -132,11 +122,8 @@ int LuaBitOps::bit_inv(lua_State* L) /*** Set each of the bits of a 24 bit integer. Returns result = result OR (1 << a1) OR (1 << a2) OR ...;) * * @function math.bit_bits - * @number a1 - * @number a2 - * @number[opt] a3 - * @number[opt] an - * @treturn number i + * @param ... integer + * @return integer result */ int LuaBitOps::bit_bits(lua_State* L) { diff --git a/rts/Lua/LuaConstCMD.cpp b/rts/Lua/LuaConstCMD.cpp index ee8b82a375..19d1ea0e19 100644 --- a/rts/Lua/LuaConstCMD.cpp +++ b/rts/Lua/LuaConstCMD.cpp @@ -11,73 +11,72 @@ /****************************************************************************** * Command constants - * @module CMD * @see rts/Lua/LuaConstCMD.cpp ******************************************************************************/ -/*** @table CMD - * - * @param FIRESTATE_NONE -1 - * @param MOVESTATE_NONE -1 - * @param STOP 0 - * @param MOVESTATE_HOLDPOS 0 - * @param FIRESTATE_HOLDFIRE 0 - * @param INSERT 1 - * @param MOVESTATE_MANEUVER 1 - * @param FIRESTATE_RETURNFIRE 1 - * @param WAITCODE_TIME 1 - * @param WAITCODE_DEATH 2 - * @param MOVESTATE_ROAM 2 - * @param REMOVE 2 - * @param FIRESTATE_FIREATWILL 2 - * @param FIRESTATE_FIREATNEUTRAL 3 - * @param WAITCODE_SQUAD 3 - * @param OPT_META 4 - * @param WAITCODE_GATHER 4 - * @param WAIT 5 - * @param TIMEWAIT 6 - * @param DEATHWAIT 7 - * @param OPT_INTERNAL 8 - * @param SQUADWAIT 8 - * @param GATHERWAIT 9 - * @param MOVE 10 - * @param PATROL 15 - * @param FIGHT 16 - * @param OPT_RIGHT 16 - * @param LOOPBACKATTACK 20 - * @param ATTACK 20 - * @param AREA_ATTACK 21 - * @param GUARD 25 - * @param OPT_SHIFT 32 - * @param GROUPSELECT 35 - * @param GROUPADD 36 - * @param GROUPCLEAR 37 - * @param REPAIR 40 - * @param FIRE_STATE 45 - * @param MOVE_STATE 50 - * @param SETBASE 55 - * @param INTERNAL 60 - * @param OPT_CTRL 64 - * @param SELFD 65 - * @param SET_WANTED_MAX_SPEED 70 - * @param LOAD_UNITS 75 - * @param LOAD_ONTO 76 - * @param UNLOAD_UNITS 80 - * @param UNLOAD_UNIT 81 - * @param ONOFF 85 - * @param RECLAIM 90 - * @param CLOAK 95 - * @param STOCKPILE 100 - * @param MANUALFIRE 105 - * @param DGUN 105 - * @param RESTORE 110 - * @param REPEAT 115 - * @param TRAJECTORY 120 - * @param RESURRECT 125 - * @param OPT_ALT 128 - * @param CAPTURE 130 - * @param AUTOREPAIRLEVEL 135 - * @param IDLEMODE 145 +/*** + * @enum CMD + * @field FIRESTATE_NONE -1 + * @field MOVESTATE_NONE -1 + * @field STOP 0 + * @field MOVESTATE_HOLDPOS 0 + * @field FIRESTATE_HOLDFIRE 0 + * @field INSERT 1 + * @field MOVESTATE_MANEUVER 1 + * @field FIRESTATE_RETURNFIRE 1 + * @field WAITCODE_TIME 1 + * @field WAITCODE_DEATH 2 + * @field MOVESTATE_ROAM 2 + * @field REMOVE 2 + * @field FIRESTATE_FIREATWILL 2 + * @field FIRESTATE_FIREATNEUTRAL 3 + * @field WAITCODE_SQUAD 3 + * @field OPT_META 4 + * @field WAITCODE_GATHER 4 + * @field WAIT 5 + * @field TIMEWAIT 6 + * @field DEATHWAIT 7 + * @field OPT_INTERNAL 8 + * @field SQUADWAIT 8 + * @field GATHERWAIT 9 + * @field MOVE 10 + * @field PATROL 15 + * @field FIGHT 16 + * @field OPT_RIGHT 16 + * @field LOOPBACKATTACK 20 + * @field ATTACK 20 + * @field AREA_ATTACK 21 + * @field GUARD 25 + * @field OPT_SHIFT 32 + * @field GROUPSELECT 35 + * @field GROUPADD 36 + * @field GROUPCLEAR 37 + * @field REPAIR 40 + * @field FIRE_STATE 45 + * @field MOVE_STATE 50 + * @field SETBASE 55 + * @field INTERNAL 60 + * @field OPT_CTRL 64 + * @field SELFD 65 + * @field SET_WANTED_MAX_SPEED 70 + * @field LOAD_UNITS 75 + * @field LOAD_ONTO 76 + * @field UNLOAD_UNITS 80 + * @field UNLOAD_UNIT 81 + * @field ONOFF 85 + * @field RECLAIM 90 + * @field CLOAK 95 + * @field STOCKPILE 100 + * @field MANUALFIRE 105 + * @field DGUN 105 + * @field RESTORE 110 + * @field REPEAT 115 + * @field TRAJECTORY 120 + * @field RESURRECT 125 + * @field OPT_ALT 128 + * @field CAPTURE 130 + * @field AUTOREPAIRLEVEL 135 + * @field IDLEMODE 145 */ diff --git a/rts/Lua/LuaConstCMDTYPE.cpp b/rts/Lua/LuaConstCMDTYPE.cpp index 5fbcff5689..372558a9b6 100644 --- a/rts/Lua/LuaConstCMDTYPE.cpp +++ b/rts/Lua/LuaConstCMDTYPE.cpp @@ -11,29 +11,28 @@ /****************************************************************************** * Command type constants - * @module CMDTYPE * @see rts/Lua/LuaConstCMDTYPE.cpp ******************************************************************************/ /*** Note, the CMDTYPE[] table is bidirectional. That means: CMDTYPE[CMDTYPE.ICON] := "CMDTYPE_ICON" * - * @table CMDTYPE - * @number ICON expect 0 parameters in return - * @number ICON_MODE expect 1 parameter in return (number selected mode) - * @number ICON_MAP expect 3 parameters in return (mappos) - * @number ICON_AREA expect 4 parameters in return (mappos+radius) - * @number ICON_UNIT expect 1 parameters in return (unitid) - * @number ICON_UNIT_OR_MAP expect 1 parameters in return (unitid) or 3 parameters in return (mappos) - * @number ICON_FRONT expect 3 or 6 parameters in return (middle and right side of front if a front was defined) - * @number COMBO_BOX expect 1 parameter in return (number selected option) - * @number ICON_UNIT_OR_AREA expect 1 parameter in return (unitid) or 4 parameters in return (mappos+radius) - * @number ICON_UNIT_FEATURE_OR_AREA expect 1 parameter in return (unitid or Game.maxUnits+featureid) or 4 parameters in return (mappos+radius) - * @number ICON_BUILDING expect 3 parameters in return (mappos) - * @number ICON_UNIT_OR_RECTANGLE expect 1 parameter in return (unitid) or 3 parameters in return (mappos) or 6 parameters in return (startpos+endpos) - * @number NUMBER expect 1 parameter in return (number) - * @number CUSTOM used with CMD_INTERNAL - * @number NEXT next command page used with CMD_INTERNAL - * @number PREV previous command page used with CMD_INTERNAL + * @enum CMDTYPE + * @field ICON number expect 0 parameters in return + * @field ICON_MODE number expect 1 parameter in return (number selected mode) + * @field ICON_MAP number expect 3 parameters in return (mappos) + * @field ICON_AREA number expect 4 parameters in return (mappos+radius) + * @field ICON_UNIT number expect 1 parameters in return (unitid) + * @field ICON_UNIT_OR_MAP number expect 1 parameters in return (unitid) or 3 parameters in return (mappos) + * @field ICON_FRONT number expect 3 or 6 parameters in return (middle and right side of front if a front was defined) + * @field COMBO_BOX number expect 1 parameter in return (number selected option) + * @field ICON_UNIT_OR_AREA number expect 1 parameter in return (unitid) or 4 parameters in return (mappos+radius) + * @field ICON_UNIT_FEATURE_OR_AREA number expect 1 parameter in return (unitid or Game.maxUnits+featureid) or 4 parameters in return (mappos+radius) + * @field ICON_BUILDING number expect 3 parameters in return (mappos) + * @field ICON_UNIT_OR_RECTANGLE number expect 1 parameter in return (unitid) or 3 parameters in return (mappos) or 6 parameters in return (startpos+endpos) + * @field NUMBER number expect 1 parameter in return (number) + * @field CUSTOM number used with CMD_INTERNAL + * @field NEXT number next command page used with CMD_INTERNAL + * @field PREV number previous command page used with CMD_INTERNAL */ bool LuaConstCMDTYPE::PushEntries(lua_State* L) diff --git a/rts/Lua/LuaConstCOB.cpp b/rts/Lua/LuaConstCOB.cpp index a919edc4c3..4078329b56 100644 --- a/rts/Lua/LuaConstCOB.cpp +++ b/rts/Lua/LuaConstCOB.cpp @@ -11,7 +11,6 @@ /****************************************************************************** * COB constants - * @module COB * @see rts/Lua/LuaConstCOB.cpp ******************************************************************************/ @@ -20,85 +19,85 @@ bool LuaConstCOB::PushEntries(lua_State* L) { #define PUSH_COB(cmd) LuaPushNamedNumber(L, #cmd, cmd) - /*** @table COB - * - * @number ACTIVATION - * @number STANDINGMOVEORDERS - * @number STANDINGFIREORDERS - * @number HEALTH - * @number INBUILDSTANCE - * @number BUSY - * @number PIECE_XZ - * @number PIECE_Y - * @number UNIT_XZ - * @number UNIT_Y - * @number UNIT_HEIGHT - * @number XZ_ATAN - * @number XZ_HYPOT - * @number ATAN - * @number HYPOT - * @number GROUND_HEIGHT - * @number BUILD_PERCENT_LEFT - * @number YARD_OPEN - * @number BUGGER_OFF - * @number ARMORED - * @number IN_WATER - * @number CURRENT_SPEED - * @number VETERAN_LEVEL - * @number ON_ROAD - * @number MAX_ID - * @number MY_ID - * @number UNIT_TEAM - * @number UNIT_BUILD_PERCENT_LEFT - * @number UNIT_ALLIED - * @number MAX_SPEED - * @number CLOAKED - * @number WANT_CLOAK - * @number GROUND_WATER_HEIGHT - * @number UPRIGHT - * @number POW - * @number PRINT - * @number HEADING - * @number TARGET_ID - * @number LAST_ATTACKER_ID - * @number LOS_RADIUS - * @number AIR_LOS_RADIUS - * @number RADAR_RADIUS - * @number JAMMER_RADIUS - * @number SONAR_RADIUS - * @number SONAR_JAM_RADIUS - * @number SEISMIC_RADIUS - * @number DO_SEISMIC_PING - * @number CURRENT_FUEL - * @number TRANSPORT_ID - * @number SHIELD_POWER - * @number STEALTH - * @number CRASHING - * @number CHANGE_TARGET - * @number CEG_DAMAGE - * @number COB_ID - * @number PLAY_SOUND - * @number KILL_UNIT - * @number ALPHA_THRESHOLD - * @number SET_WEAPON_UNIT_TARGET - * @number SET_WEAPON_GROUND_TARGET - * @number SONAR_STEALTH - * @number REVERSING - * @number FLANK_B_MODE - * @number FLANK_B_DIR - * @number FLANK_B_MOBILITY_ADD - * @number FLANK_B_MAX_DAMAGE - * @number FLANK_B_MIN_DAMAGE - * @number WEAPON_RELOADSTATE - * @number WEAPON_RELOADTIME - * @number WEAPON_ACCURACY - * @number WEAPON_SPRAY - * @number WEAPON_RANGE - * @number WEAPON_PROJECTILE_SPEED - * @number MIN - * @number MAX - * @number ABS - * @number GAME_FRAME + /*** + * @enum COB + * @field ACTIVATION number + * @field STANDINGMOVEORDERS number + * @field STANDINGFIREORDERS number + * @field HEALTH number + * @field INBUILDSTANCE number + * @field BUSY number + * @field PIECE_XZ number + * @field PIECE_Y number + * @field UNIT_XZ number + * @field UNIT_Y number + * @field UNIT_HEIGHT number + * @field XZ_ATAN number + * @field XZ_HYPOT number + * @field ATAN number + * @field HYPOT number + * @field GROUND_HEIGHT number + * @field BUILD_PERCENT_LEFT number + * @field YARD_OPEN number + * @field BUGGER_OFF number + * @field ARMORED number + * @field IN_WATER number + * @field CURRENT_SPEED number + * @field VETERAN_LEVEL number + * @field ON_ROAD number + * @field MAX_ID number + * @field MY_ID number + * @field UNIT_TEAM number + * @field UNIT_BUILD_PERCENT_LEFT number + * @field UNIT_ALLIED number + * @field MAX_SPEED number + * @field CLOAKED number + * @field WANT_CLOAK number + * @field GROUND_WATER_HEIGHT number + * @field UPRIGHT number + * @field POW number + * @field PRINT number + * @field HEADING number + * @field TARGET_ID number + * @field LAST_ATTACKER_ID number + * @field LOS_RADIUS number + * @field AIR_LOS_RADIUS number + * @field RADAR_RADIUS number + * @field JAMMER_RADIUS number + * @field SONAR_RADIUS number + * @field SONAR_JAM_RADIUS number + * @field SEISMIC_RADIUS number + * @field DO_SEISMIC_PING number + * @field CURRENT_FUEL number + * @field TRANSPORT_ID number + * @field SHIELD_POWER number + * @field STEALTH number + * @field CRASHING number + * @field CHANGE_TARGET number + * @field CEG_DAMAGE number + * @field COB_ID number + * @field PLAY_SOUND number + * @field KILL_UNIT number + * @field ALPHA_THRESHOLD number + * @field SET_WEAPON_UNIT_TARGET number + * @field SET_WEAPON_GROUND_TARGET number + * @field SONAR_STEALTH number + * @field REVERSING number + * @field FLANK_B_MODE number + * @field FLANK_B_DIR number + * @field FLANK_B_MOBILITY_ADD number + * @field FLANK_B_MAX_DAMAGE number + * @field FLANK_B_MIN_DAMAGE number + * @field WEAPON_RELOADSTATE number + * @field WEAPON_RELOADTIME number + * @field WEAPON_ACCURACY number + * @field WEAPON_SPRAY number + * @field WEAPON_RANGE number + * @field WEAPON_PROJECTILE_SPEED number + * @field MIN number + * @field MAX number + * @field ABS number + * @field GAME_FRAME number */ PUSH_COB(ACTIVATION); @@ -201,20 +200,68 @@ bool LuaConstCOB::PushEntries(lua_State* L) bool LuaConstSFX::PushEntries(lua_State* L) { - /*** Piece Flags for Spring.UnitScript.Explode - * - * @table SFX - * - * @number SHATTER - * @number EXPLODE - * @number EXPLODE_ON_HIT - * @number FALL - * @number SMOKE - * @number FIRE - * @number NONE - * @number NO_CEG_TRAIL - * @number NO_HEATCLOUD - * @number RECURSIVE + /*** + * @enum SFX + * + * @field SHATTER number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field EXPLODE number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field EXPLODE_ON_HIT number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field FALL number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field SMOKE number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field FIRE number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field NONE number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field NO_CEG_TRAIL number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field NO_HEATCLOUD number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field RECURSIVE number + * Piece Flag for `Spring.UnitScript.Explode` + * + * @field VTOL number + * For `Spring.UnitScript.EmitSfx`. + * + * @field WAKE number + * For `Spring.UnitScript.EmitSfx`. + * + * @field REVERSE_WAKE number + * For `Spring.UnitScript.EmitSfx`. + * + * @field WHITE_SMOKE number + * For `Spring.UnitScript.EmitSfx`. + * + * @field BLACK_SMOKE number + * For `Spring.UnitScript.EmitSfx`. + * + * @field BUBBLE number + * For `Spring.UnitScript.EmitSfx`. + * + * @field CEG number + * For `Spring.UnitScript.EmitSfx`. + * + * @field FIRE_WEAPON number + * For `Spring.UnitScript.EmitSfx`. + * + * @field DETONATE_WEAPON number + * For `Spring.UnitScript.EmitSfx`. + * + * @field GLOBAL number + * For `Spring.UnitScript.EmitSfx`. */ LuaPushNamedNumber(L, "SHATTER", PF_Shatter); LuaPushNamedNumber(L, "EXPLODE", PF_Explode); @@ -227,21 +274,6 @@ bool LuaConstSFX::PushEntries(lua_State* L) LuaPushNamedNumber(L, "NO_HEATCLOUD", PF_NoHeatCloud); LuaPushNamedNumber(L, "RECURSIVE", PF_Recursive); - /*** For Spring.UnitScript.EmitSfx - * - * @table SFX - * - * @number VTOL - * @number WAKE - * @number REVERSE_WAKE - * @number WHITE_SMOKE - * @number BLACK_SMOKE - * @number BUBBLE - * @number CEG - * @number FIRE_WEAPON - * @number DETONATE_WEAPON - * @number GLOBAL - */ LuaPushNamedNumber(L, "VTOL", SFX_VTOL); LuaPushNamedNumber(L, "WAKE", SFX_WAKE); LuaPushNamedNumber(L, "REVERSE_WAKE", SFX_REVERSE_WAKE); diff --git a/rts/Lua/LuaConstEngine.cpp b/rts/Lua/LuaConstEngine.cpp index 54b8b7a60b..ffaeb80656 100644 --- a/rts/Lua/LuaConstEngine.cpp +++ b/rts/Lua/LuaConstEngine.cpp @@ -8,22 +8,29 @@ /****************************************************************************** * Engine constants - * @module Engine * @see rts/Lua/LuaConstEngine.cpp ******************************************************************************/ -/*** Engine specific information +/*** + * @class FeatureSupport + * @field NegativeGetUnitCurrentCommand boolean + * @field hasExitOnlyYardmaps boolean + * @field rmlUiApiVersion integer + */ + +/*** + * Engine specific information. * * @table Engine - * @string version "Major.Minor.PatchSet" for releases, "Major.Minor.PatchSet-CommitNum-gHash branch" otherwise - * @string versionFull "Major.Minor.PatchSet" for releases, "Major.Minor.PatchSet-CommitNum-gHash branch" otherwise. Will also include (buildFlags), if there're any. - * @string versionMajor - Major part of the named release version - * @string versionMinor - Minor part of the named release version - * @string versionPatchSet - Build numbert of the named release version - * @string commitsNumber - number of commits after the latest named release, non-zero indicates a "dev" build - * @string buildFlags Gets additional engine buildflags, e.g. "Debug" or "Sync-Debug" - * @string FeatureSupport table containing various engine features as keys; use for cross-version compat - * @number wordSize indicates the build type always 64 these days + * @field version string "Major.Minor.PatchSet" for releases, "Major.Minor.PatchSet-CommitNum-gHash branch" otherwise + * @field versionFull string "Major.Minor.PatchSet" for releases, "Major.Minor.PatchSet-CommitNum-gHash branch" otherwise. Will also include (buildFlags), if there're any. + * @field versionMajor string Major part of the named release version + * @field versionMinor string Minor part of the named release version + * @field versionPatchSet string Build numbert of the named release version + * @field commitsNumber string Number of commits after the latest named release, non-zero indicates a "dev" build + * @field buildFlags string Gets additional engine buildflags, e.g. "Debug" or "Sync-Debug" + * @field featureSupport FeatureSupport Table containing various engine features as keys; use for cross-version compat + * @field wordSize number Indicates the build type always 64 these days */ bool LuaConstEngine::PushEntries(lua_State* L) @@ -54,4 +61,3 @@ bool LuaConstEngine::PushEntries(lua_State* L) return true; } - diff --git a/rts/Lua/LuaConstGL.cpp b/rts/Lua/LuaConstGL.cpp index 2b24bc1252..495947b744 100644 --- a/rts/Lua/LuaConstGL.cpp +++ b/rts/Lua/LuaConstGL.cpp @@ -11,7 +11,6 @@ /****************************************************************************** * OpenGL Constants - * @module GL * @see rts/Lua/LuaConstGL.cpp ******************************************************************************/ @@ -24,19 +23,20 @@ bool LuaConstGL::PushEntries(lua_State* L) * @section primitives */ - /*** @table GL + /*** + * @enum GL * - * @number POINTS - * @number LINES - * @number LINE_LOOP - * @number LINE_STRIP - * @number TRIANGLES - * @number TRIANGLE_STRIP - * @number TRIANGLE_FAN - * @number QUADS - * @number QUAD_STRIP - * @number POLYGON - * @number PATCHES + * @field POINTS number + * @field LINES number + * @field LINE_LOOP number + * @field LINE_STRIP number + * @field TRIANGLES number + * @field TRIANGLE_STRIP number + * @field TRIANGLE_FAN number + * @field QUADS number + * @field QUAD_STRIP number + * @field POLYGON number + * @field PATCHES number */ PUSH_GL(POINTS); PUSH_GL(LINES); @@ -62,14 +62,14 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** @table GL * - * @number ZERO - * @number ONE - * @number SRC_COLOR - * @number ONE_MINUS_SRC_COLOR - * @number SRC_ALPHA - * @number ONE_MINUS_SRC_ALPHA - * @number DST_ALPHA - * @number ONE_MINUS_DST_ALPHA + * @field ZERO number + * @field ONE number + * @field SRC_COLOR number + * @field ONE_MINUS_SRC_COLOR number + * @field SRC_ALPHA number + * @field ONE_MINUS_SRC_ALPHA number + * @field DST_ALPHA number + * @field ONE_MINUS_DST_ALPHA number */ PUSH_GL(ZERO); PUSH_GL(ONE); @@ -87,22 +87,22 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number ZERO - * @number ONE - * @number SRC_COLOR - * @number ONE_MINUS_SRC_COLOR - * @number SRC_ALPHA - * @number ONE_MINUS_SRC_ALPHA - * @number DST_ALPHA - * @number ONE_MINUS_DST_ALPHA - * @number DST_COLOR - * @number ONE_MINUS_DST_COLOR - * @number SRC_ALPHA_SATURATE - * @number FUNC_ADD - * @number FUNC_SUBTRACT - * @number FUNC_REVERSE_SUBTRACT - * @number MIN - * @number MAX + * @field ZERO number + * @field ONE number + * @field SRC_COLOR number + * @field ONE_MINUS_SRC_COLOR number + * @field SRC_ALPHA number + * @field ONE_MINUS_SRC_ALPHA number + * @field DST_ALPHA number + * @field ONE_MINUS_DST_ALPHA number + * @field DST_COLOR number + * @field ONE_MINUS_DST_COLOR number + * @field SRC_ALPHA_SATURATE number + * @field FUNC_ADD number + * @field FUNC_SUBTRACT number + * @field FUNC_REVERSE_SUBTRACT number + * @field MIN number + * @field MAX number */ PUSH_GL(DST_COLOR); PUSH_GL(ONE_MINUS_DST_COLOR); @@ -121,14 +121,14 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** @table GL * - * @number NEVER - * @number LESS - * @number EQUAL - * @number LEQUAL - * @number GREATER - * @number NOTEQUAL - * @number GEQUAL - * @number ALWAYS + * @field NEVER number + * @field LESS number + * @field EQUAL number + * @field LEQUAL number + * @field GREATER number + * @field NOTEQUAL number + * @field GEQUAL number + * @field ALWAYS number */ PUSH_GL(NEVER); PUSH_GL(LESS); @@ -146,22 +146,22 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number CLEAR - * @number AND - * @number AND_REVERSE - * @number COPY - * @number AND_INVERTED - * @number NOOP - * @number XOR - * @number OR - * @number NOR - * @number EQUIV - * @number INVERT - * @number OR_REVERSE - * @number COPY_INVERTED - * @number OR_INVERTED - * @number NAND - * @number SET + * @field CLEAR number + * @field AND number + * @field AND_REVERSE number + * @field COPY number + * @field AND_INVERTED number + * @field NOOP number + * @field XOR number + * @field OR number + * @field NOR number + * @field EQUIV number + * @field INVERT number + * @field OR_REVERSE number + * @field COPY_INVERTED number + * @field OR_INVERTED number + * @field NAND number + * @field SET number */ PUSH_GL(CLEAR); PUSH_GL(AND); @@ -187,9 +187,9 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number BACK - * @number FRONT - * @number FRONT_AND_BACK + * @field BACK number + * @field FRONT number + * @field FRONT_AND_BACK number */ PUSH_GL(BACK); PUSH_GL(FRONT); @@ -202,9 +202,9 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number POINT - * @number LINE - * @number FILL + * @field POINT number + * @field LINE number + * @field FILL number */ PUSH_GL(POINT); PUSH_GL(LINE); @@ -217,10 +217,10 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number DEPTH_BUFFER_BIT - * @number ACCUM_BUFFER_BIT - * @number STENCIL_BUFFER_BIT - * @number COLOR_BUFFER_BIT + * @field DEPTH_BUFFER_BIT number + * @field ACCUM_BUFFER_BIT number + * @field STENCIL_BUFFER_BIT number + * @field COLOR_BUFFER_BIT number */ PUSH_GL(DEPTH_BUFFER_BIT); PUSH_GL(ACCUM_BUFFER_BIT); @@ -234,8 +234,8 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number FLAT - * @number SMOOTH + * @field FLAT number + * @field SMOOTH number */ PUSH_GL(FLAT); PUSH_GL(SMOOTH); @@ -247,9 +247,9 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number MODELVIEW - * @number PROJECTION - * @number TEXTURE + * @field MODELVIEW number + * @field PROJECTION number + * @field TEXTURE number */ PUSH_GL(MODELVIEW); PUSH_GL(PROJECTION); @@ -262,12 +262,12 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number NEAREST - * @number LINEAR - * @number NEAREST_MIPMAP_NEAREST - * @number LINEAR_MIPMAP_NEAREST - * @number NEAREST_MIPMAP_LINEAR - * @number LINEAR_MIPMAP_LINEAR + * @field NEAREST number + * @field LINEAR number + * @field NEAREST_MIPMAP_NEAREST number + * @field LINEAR_MIPMAP_NEAREST number + * @field NEAREST_MIPMAP_LINEAR number + * @field LINEAR_MIPMAP_LINEAR number */ PUSH_GL(NEAREST); PUSH_GL(LINEAR); @@ -283,11 +283,11 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number REPEAT - * @number MIRRORED_REPEAT - * @number CLAMP - * @number CLAMP_TO_EDGE - * @number CLAMP_TO_BORDER + * @field REPEAT number + * @field MIRRORED_REPEAT number + * @field CLAMP number + * @field CLAMP_TO_EDGE number + * @field CLAMP_TO_BORDER number */ PUSH_GL(REPEAT); PUSH_GL(MIRRORED_REPEAT); @@ -302,13 +302,13 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number TEXTURE_ENV - * @number TEXTURE_ENV_MODE - * @number TEXTURE_ENV_COLOR - * @number MODULATE - * @number DECAL - * @number BLEND - * @number REPLACE + * @field TEXTURE_ENV number + * @field TEXTURE_ENV_MODE number + * @field TEXTURE_ENV_COLOR number + * @field MODULATE number + * @field DECAL number + * @field BLEND number + * @field REPLACE number */ PUSH_GL(TEXTURE_ENV); PUSH_GL(TEXTURE_ENV_MODE); @@ -330,18 +330,18 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number TEXTURE_GEN_MODE - * @number EYE_PLANE - * @number OBJECT_PLANE - * @number EYE_LINEAR - * @number OBJECT_LINEAR - * @number SPHERE_MAP - * @number NORMAL_MAP - * @number REFLECTION_MAP - * @number S - * @number T - * @number R - * @number Q + * @field TEXTURE_GEN_MODE number + * @field EYE_PLANE number + * @field OBJECT_PLANE number + * @field EYE_LINEAR number + * @field OBJECT_LINEAR number + * @field SPHERE_MAP number + * @field NORMAL_MAP number + * @field REFLECTION_MAP number + * @field S number + * @field T number + * @field R number + * @field Q number */ PUSH_GL(TEXTURE_GEN_MODE); PUSH_GL(EYE_PLANE); @@ -363,27 +363,27 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number CURRENT_BIT - * @number POINT_BIT - * @number LINE_BIT - * @number POLYGON_BIT - * @number POLYGON_STIPPLE_BIT - * @number PIXEL_MODE_BIT - * @number LIGHTING_BIT - * @number FOG_BIT - * @number DEPTH_BUFFER_BIT - * @number ACCUM_BUFFER_BIT - * @number STENCIL_BUFFER_BIT - * @number VIEWPORT_BIT - * @number TRANSFORM_BIT - * @number ENABLE_BIT - * @number COLOR_BUFFER_BIT - * @number HINT_BIT - * @number EVAL_BIT - * @number LIST_BIT - * @number TEXTURE_BIT - * @number SCISSOR_BIT - * @number ALL_ATTRIB_BITS + * @field CURRENT_BIT number + * @field POINT_BIT number + * @field LINE_BIT number + * @field POLYGON_BIT number + * @field POLYGON_STIPPLE_BIT number + * @field PIXEL_MODE_BIT number + * @field LIGHTING_BIT number + * @field FOG_BIT number + * @field DEPTH_BUFFER_BIT number + * @field ACCUM_BUFFER_BIT number + * @field STENCIL_BUFFER_BIT number + * @field VIEWPORT_BIT number + * @field TRANSFORM_BIT number + * @field ENABLE_BIT number + * @field COLOR_BUFFER_BIT number + * @field HINT_BIT number + * @field EVAL_BIT number + * @field LIST_BIT number + * @field TEXTURE_BIT number + * @field SCISSOR_BIT number + * @field ALL_ATTRIB_BITS number */ PUSH_GL(CURRENT_BIT); PUSH_GL(POINT_BIT); @@ -415,11 +415,11 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number FOG_HINT - * @number LINE_SMOOTH_HINT - * @number POINT_SMOOTH_HINT - * @number POLYGON_SMOOTH_HINT - * @number PERSPECTIVE_CORRECTION_HINT + * @field FOG_HINT number + * @field LINE_SMOOTH_HINT number + * @field POINT_SMOOTH_HINT number + * @field POLYGON_SMOOTH_HINT number + * @field PERSPECTIVE_CORRECTION_HINT number */ PUSH_GL(FOG_HINT); PUSH_GL(PERSPECTIVE_CORRECTION_HINT); @@ -431,9 +431,9 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number DONT_CARE - * @number FASTEST - * @number NICEST + * @field DONT_CARE number + * @field FASTEST number + * @field NICEST number */ PUSH_GL(DONT_CARE); PUSH_GL(FASTEST); @@ -446,16 +446,16 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number AMBIENT - * @number DIFFUSE - * @number SPECULAR - * @number POSITION - * @number SPOT_DIRECTION - * @number SPOT_EXPONENT - * @number SPOT_CUTOFF - * @number CONSTANT_ATTENUATION - * @number LINEAR_ATTENUATION - * @number QUADRATIC_ATTENUATION + * @field AMBIENT number + * @field DIFFUSE number + * @field SPECULAR number + * @field POSITION number + * @field SPOT_DIRECTION number + * @field SPOT_EXPONENT number + * @field SPOT_CUTOFF number + * @field CONSTANT_ATTENUATION number + * @field LINEAR_ATTENUATION number + * @field QUADRATIC_ATTENUATION number */ PUSH_GL(AMBIENT); PUSH_GL(DIFFUSE); @@ -475,11 +475,11 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number VERTEX_SHADER - * @number TESS_CONTROL_SHADER - * @number TESS_EVALUATION_SHADER - * @number GEOMETRY_SHADER - * @number FRAGMENT_SHADER + * @field VERTEX_SHADER number + * @field TESS_CONTROL_SHADER number + * @field TESS_EVALUATION_SHADER number + * @field GEOMETRY_SHADER number + * @field FRAGMENT_SHADER number */ PUSH_GL(VERTEX_SHADER); PUSH_GL(TESS_CONTROL_SHADER); @@ -494,9 +494,9 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number GEOMETRY_INPUT_TYPE - * @number GEOMETRY_OUTPUT_TYPE - * @number GEOMETRY_VERTICES_OUT + * @field GEOMETRY_INPUT_TYPE number + * @field GEOMETRY_OUTPUT_TYPE number + * @field GEOMETRY_VERTICES_OUT number */ PUSH_GL(GEOMETRY_INPUT_TYPE_EXT); PUSH_GL(GEOMETRY_OUTPUT_TYPE_EXT); @@ -509,9 +509,9 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number PATCH_VERTICES - * @number PATCH_DEFAULT_OUTER_LEVEL - * @number PATCH_DEFAULT_INNER_LEVEL + * @field PATCH_VERTICES number + * @field PATCH_DEFAULT_OUTER_LEVEL number + * @field PATCH_DEFAULT_INNER_LEVEL number */ PUSH_GL(PATCH_VERTICES); PUSH_GL(PATCH_DEFAULT_OUTER_LEVEL); @@ -524,17 +524,17 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number BYTE - * @number UNSIGNED_BYTE - * @number SHORT - * @number UNSIGNED_SHORT - * @number INT - * @number UNSIGNED_INT - * @number FLOAT - * @number FLOAT_VEC4 - * @number INT_VEC4 - * @number UNSIGNED_INT_VEC4 - * @number FLOAT_MAT4 + * @field BYTE number + * @field UNSIGNED_BYTE number + * @field SHORT number + * @field UNSIGNED_SHORT number + * @field INT number + * @field UNSIGNED_INT number + * @field FLOAT number + * @field FLOAT_VEC4 number + * @field INT_VEC4 number + * @field UNSIGNED_INT_VEC4 number + * @field FLOAT_MAT4 number */ PUSH_GL(BYTE); PUSH_GL(UNSIGNED_BYTE); @@ -555,10 +555,10 @@ bool LuaConstGL::PushEntries(lua_State* L) /*** * @table GL - * @number ELEMENT_ARRAY_BUFFER - * @number ARRAY_BUFFER - * @number UNIFORM_BUFFER - * @number SHADER_STORAGE_BUFFER + * @field ELEMENT_ARRAY_BUFFER number + * @field ARRAY_BUFFER number + * @field UNIFORM_BUFFER number + * @field SHADER_STORAGE_BUFFER number * */ PUSH_GL(ELEMENT_ARRAY_BUFFER); diff --git a/rts/Lua/LuaConstGame.cpp b/rts/Lua/LuaConstGame.cpp index 6c5cdd331a..8d536dfb51 100644 --- a/rts/Lua/LuaConstGame.cpp +++ b/rts/Lua/LuaConstGame.cpp @@ -25,65 +25,65 @@ /****************************************************************************** * Game constants - * @module Game * @see rts/Lua/LuaConstGame.cpp ******************************************************************************/ /*** Game specific information * * @table Game - * @number maxUnits - * @number maxTeams - * @number maxPlayers - * @number squareSize Divide Game.mapSizeX or Game.mapSizeZ by this to get engine's "mapDims" coordinates. The resolution of height, yard and type maps. - * @number metalMapSquareSize The resolution of metalmap (for use in API such as Spring.GetMetalAmount etc.) - * @number gameSpeed - * @number startPosType - * @bool ghostedBuildings - * @string mapChecksum - * @string modChecksum - * @bool mapDamage - * @string mapName - * @string mapDescription = string Game.mapHumanName - * @number mapHardness - * @number mapX - * @number mapY - * @number mapSizeX in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates - * @number mapSizeZ in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates - * @number gravity - * @number tidal - * @number windMin - * @number windMax - * @number extractorRadius - * @number waterDamage - * @tparam table envDamageTypes Containing {def}IDs of environmental-damage sources - * @string gameName - * @string gameShortName - * @string gameVersion - * @string gameMutator - * @string gameDesc - * @bool requireSonarUnderWater - * @number transportAir - * @number transportShip - * @number transportHover - * @number transportGround - * @number fireAtKilled - * @number fireAtCrashing - * @bool constructionDecay - * @bool reclaimAllowEnemies - * @bool reclaimAllowAllies - * @number constructionDecayTime - * @number constructionDecaySpeed - * @number multiReclaim - * @number reclaimMethod - * @number reclaimUnitMethod - * @number reclaimUnitEnergyCostFactor - * @number reclaimUnitEfficiency - * @number reclaimFeatureEnergyCostFactor - * @number repairEnergyCostFactor - * @number resurrectEnergyCostFactor - * @number captureEnergyCostFactor - * @tparam table springCategories + * @field maxUnits number + * @field maxTeams number + * @field maxPlayers number + * @field squareSize number Divide Game.mapSizeX or Game.mapSizeZ by this to get engine's "mapDims" coordinates. The resolution of height, yard and type maps. + * @field metalMapSquareSize number The resolution of metalmap (for use in API such as Spring.GetMetalAmount etc.) + * @field gameSpeed number + * @field startPosType number + * @field ghostedBuildings boolean + * @field mapChecksum string + * @field modChecksum string + * @field mapDamage boolean + * @field mapName string + * @field mapDescription string = string Game.mapHumanName + * @field mapHardness number + * @field mapX number + * @field mapY number + * @field mapSizeX number in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates + * @field mapSizeZ number in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates + * @field gravity number + * @field tidal number + * @field windMin number + * @field windMax number + * @field extractorRadius number + * @field waterDamage number + * @field envDamageTypes table Containing {def}IDs of environmental-damage sources + * @field gameName string + * @field gameShortName string + * @field gameVersion string + * @field gameMutator string + * @field gameDesc string + * @field requireSonarUnderWater boolean + * @field transportAir number + * @field transportShip number + * @field transportHover number + * @field transportGround number + * @field fireAtKilled number + * @field fireAtCrashing number + * @field constructionDecay boolean + * @field reclaimAllowEnemies boolean + * @field reclaimAllowAllies boolean + * @field constructionDecayTime number + * @field constructionDecaySpeed number + * @field multiReclaim number + * @field reclaimMethod number + * @field reclaimUnitMethod number + * @field reclaimUnitEnergyCostFactor number + * @field reclaimUnitEfficiency number + * @field reclaimFeatureEnergyCostFactor number + * @field repairEnergyCostFactor number + * @field resurrectEnergyCostFactor number + * @field captureEnergyCostFactor number + * @field springCategories table + * ```lua * example: { * ["vtol"] = 0, ["special"] = 1, ["noweapon"] = 2, * ["notair"] = 3, ["notsub"] = 4, ["all"] = 5, @@ -97,7 +97,9 @@ * ["kamikaze"] = 27, ["minelayer"] = 28, ["notstructure"] = 29, * ["air"] = 30 * } - * @tparam table armorTypes (bidirectional) + * ``` + * @field armorTypes table (bidirectional) + * ```lua * example: { * [1] = amphibious, [2] = anniddm, [3] = antibomber, * [4] = antifighter, [5] = antiraider, [6] = atl, @@ -109,6 +111,7 @@ * ["blackhydra"] = 7, ["bombers"] = 8, ["commanders"] = 9 * ["crawlingbombs"]= 10, ... * } + * ``` */ bool LuaConstGame::PushEntries(lua_State* L) diff --git a/rts/Lua/LuaConstPlatform.cpp b/rts/Lua/LuaConstPlatform.cpp index ddc90e0435..ec0603ec9f 100644 --- a/rts/Lua/LuaConstPlatform.cpp +++ b/rts/Lua/LuaConstPlatform.cpp @@ -9,39 +9,38 @@ /****************************************************************************** * Platform constants - * @module Platform * @see rts/Lua/LuaConstPlatform.cpp ******************************************************************************/ /*** Platform specific information * * @table Platform - * @string gpu full GPU device name - * @string gpuVendor one of "Nvidia", "Intel", "ATI", "Mesa", "Unknown" - * @string glVersionShort major.minor.buildNumber - * @string glslVersionShort major.minor - * @string glVersion full version - * @string glVendor - * @string glRenderer - * @string glslVersion full version - * @string glewVersion - * @string osName full name of the OS - * @string osFamily one of "Windows", "Linux", "MacOSX", "FreeBSD", "Unknown" - * @number numDisplays - * @number gpuMemorySize size of total GPU memory in MBs; only available for "Nvidia", (rest are 0) - * @number sdlVersionCompiledMajor - * @number sdlVersionCompiledMinor - * @number sdlVersionCompiledPatch - * @number sdlVersionLinkedMajor - * @number sdlVersionLinkedMinor - * @number sdlVersionLinkedPatch - * @number totalRAM Total physical system RAM in MBs. - * @bool glSupportNonPowerOfTwoTex - * @bool glSupportTextureQueryLOD - * @bool glSupport24bitDepthBuffer - * @bool glSupportRestartPrimitive - * @bool glSupportClipSpaceControl - * @bool glSupportFragDepthLayout + * @field gpu string Full GPU device name + * @field gpuVendor "Nvidia"|"Intel"|"ATI"|"Mesa"|"Unknown" + * @field glVersionShort string `major.minor.buildNumber` + * @field glslVersionShort string `major.minor` + * @field glVersion string Full version + * @field glVendor string + * @field glRenderer string + * @field glslVersion string Full version + * @field glewVersion string + * @field osName string full name of the OS + * @field osFamily "Windows"|"Linux"|"MacOSX"|"FreeBSD"|"Unknown" + * @field numDisplays number + * @field gpuMemorySize number Size of total GPU memory in MBs; only available for "Nvidia", (rest are 0) + * @field sdlVersionCompiledMajor number + * @field sdlVersionCompiledMinor number + * @field sdlVersionCompiledPatch number + * @field sdlVersionLinkedMajor number + * @field sdlVersionLinkedMinor number + * @field sdlVersionLinkedPatch number + * @field totalRAM number Total physical system RAM in MBs. + * @field glSupportNonPowerOfTwoTex boolean + * @field glSupportTextureQueryLOD boolean + * @field glSupport24bitDepthBuffer boolean + * @field glSupportRestartPrimitive boolean + * @field glSupportClipSpaceControl boolean + * @field glSupportFragDepthLayout boolean */ bool LuaConstPlatform::PushEntries(lua_State* L) diff --git a/rts/Lua/LuaFBOs.cpp b/rts/Lua/LuaFBOs.cpp index 80ead41aaf..a709116aa8 100644 --- a/rts/Lua/LuaFBOs.cpp +++ b/rts/Lua/LuaFBOs.cpp @@ -22,7 +22,6 @@ /****************************************************************************** * FBO - * @module FBO * @see rts/Lua/LuaFBOs.cpp ******************************************************************************/ @@ -409,36 +408,32 @@ bool LuaFBOs::ApplyDrawBuffers(lua_State* L, int index) /******************************************************************************/ /******************************************************************************/ +/** + * @table gl + */ + /*** - * @table attachment * attachment ::= luaTex or `RBO.rbo` or nil or { luaTex [, num target [, num level ] ] } + * @class attachment */ /*** * User Data FBO - * @table fbo - * @tparam attachment depth - * @tparam attachment stencil - * @tparam attachment color0 - * @tparam attachment color1 - * @tparam attachment color2 - * @tparam attachment colorn - * @tparam attachment color15 - * @tparam table drawbuffers `{ GL_COLOR_ATTACHMENT0_EXT, GL_COLOR_ATTACHMENT3_EXT, ..}` - * @tparam table readbuffer `GL_COLOR_ATTACHMENT0_EXT` + * @class Fbo + * @field depth attachment + * @field stencil attachment + * @field color0 attachment + * @field color1 attachment + * @field color2 attachment + * @field colorn attachment + * @field color15 attachment + * @field drawbuffers table `{ GL_COLOR_ATTACHMENT0_EXT, GL_COLOR_ATTACHMENT3_EXT, ..}` + * @field readbuffer table `GL_COLOR_ATTACHMENT0_EXT` */ /*** * @function gl.CreateFBO - * @param data - * @tparam attachment data.depth - * @tparam attachment data.stencil - * @tparam attachment data.color0 - * @tparam attachment data.color1 - * @tparam attachment data.color2 - * @tparam attachment data.colorn - * @tparam attachment data.color15 - * @tparam table data.drawbuffers `{ GL_COLOR_ATTACHMENT0_EXT, GL_COLOR_ATTACHMENT3_EXT, ..}` + * @param fbo Fbo */ int LuaFBOs::CreateFBO(lua_State* L) { @@ -511,9 +506,10 @@ int LuaFBOs::CreateFBO(lua_State* L) /*** - * @function gl.DeleteFBO * This doesn't delete the attached objects! - * @tparam fbo fbo + * + * @function gl.DeleteFBO + * @param fbo Fbo */ int LuaFBOs::DeleteFBO(lua_State* L) { @@ -529,10 +525,10 @@ int LuaFBOs::DeleteFBO(lua_State* L) /*** * @function gl.IsValidFBO - * @tparam fbo fbo - * @number[opt] target - * @treturn bool valid - * @treturn ?number status + * @param fbo Fbo + * @param target GL? + * @return boolean valid + * @return number? status */ int LuaFBOs::IsValidFBO(lua_State* L) { @@ -571,13 +567,13 @@ int LuaFBOs::IsValidFBO(lua_State* L) /*** * @function gl.ActiveFBO - * @tparam fbo fbo - * @number[opt] target - * @bool[opt] identities - * @func[opt] lua_function - * @param[opt] arg1 - * @param[opt] arg2 - * @param[opt] argn + * @param fbo Fbo + * @param target GL? + * @param identities boolean? + * @param lua_function function? + * @param arg1 any? + * @param arg2 any? + * @param argn any? */ int LuaFBOs::ActiveFBO(lua_State* L) { @@ -643,10 +639,19 @@ int LuaFBOs::ActiveFBO(lua_State* L) /** - *gl.RawBindFBO - * - * ( nil [, number target = GL_FRAMEBUFFER_EXT ] [, number rawFboId = 0] ) -> nil (Bind default or specified via rawFboId numeric id of FBO) - * ( fbo [, number target = fbo.target ] ) -> number previouslyBoundRawFboId + * Bind default or specified via rawFboId numeric id of FBO + * + * @function gl.RawBindFBO + * @param fbo nil + * @param target GL? (Default: `GL_FRAMEBUFFER_EXT`) + * @param rawFboId integer? (Default: 0) + * @return nil + */ +/** + * @function gl.RawBindFBO + * @param fbo Fbo + * @param target GL? (Default: `fbo.target`) + * @return number previouslyBoundRawFboId */ int LuaFBOs::RawBindFBO(lua_State* L) { @@ -678,32 +683,32 @@ int LuaFBOs::RawBindFBO(lua_State* L) /*** needs `GLEW_EXT_framebuffer_blit` * * @function gl.BlitFBO - * @number x0Src - * @number y0Src - * @number x1Src - * @number y1Src - * @number x0Dst - * @number y0Dst - * @number x1Dst - * @number y1Dst - * @number[opt=GL_COLOR_BUFFER_BIT] mask - * @number[opt=GL_NEAREST] filter + * @param x0Src number + * @param y0Src number + * @param x1Src number + * @param y1Src number + * @param x0Dst number + * @param y0Dst number + * @param x1Dst number + * @param y1Dst number + * @param mask number? (Default: GL_COLOR_BUFFER_BIT) + * @param filter number? (Default: GL_NEAREST) */ /*** needs `GLEW_EXT_framebuffer_blit` * * @function gl.BlitFBO - * @tparam fbo fboSrc - * @number x0Src - * @number y0Src - * @number x1Src - * @number y1Src - * @tparam fbo fboDst - * @number x0Dst - * @number y0Dst - * @number x1Dst - * @number y1Dst - * @number[opt=GL_COLOR_BUFFER_BIT] mask - * @number[opt=GL_NEAREST] filter + * @param fboSrc Fbo + * @param x0Src number + * @param y0Src number + * @param x1Src number + * @param y1Src number + * @param fboDst Fbo + * @param x0Dst number + * @param y0Dst number + * @param x1Dst number + * @param y1Dst number + * @param mask number? (Default: GL_COLOR_BUFFER_BIT) + * @param filter number? (Default: GL_NEAREST) */ int LuaFBOs::BlitFBO(lua_State* L) { diff --git a/rts/Lua/LuaFonts.cpp b/rts/Lua/LuaFonts.cpp index 5e4881a17f..55d3a16916 100644 --- a/rts/Lua/LuaFonts.cpp +++ b/rts/Lua/LuaFonts.cpp @@ -221,8 +221,8 @@ int LuaFonts::DeleteFont(lua_State* L) * but later, on the Update cycle (before other Update and Draw callins). * * @function gl.AddFallbackFont - * @string filePath VFS path to the file, for example "fonts/myfont.ttf". Uses VFS.RAW_FIRST access mode. - * @treturn bool success + * @param filePath string VFS path to the file, for example "fonts/myfont.ttf". Uses VFS.RAW_FIRST access mode. + * @return bool success */ int LuaFonts::AddFallbackFont(lua_State* L) { @@ -241,7 +241,7 @@ int LuaFonts::AddFallbackFont(lua_State* L) * it also applies when calling this method. * * @function gl.ClearFallbackFonts - * @treturn nil + * @return nil */ int LuaFonts::ClearFallbackFonts(lua_State* L) { @@ -502,4 +502,3 @@ int LuaFonts::BindTexture(lua_State* L) return 0; } - diff --git a/rts/Lua/LuaHandle.cpp b/rts/Lua/LuaHandle.cpp index 28864d1741..2705a951a9 100644 --- a/rts/Lua/LuaHandle.cpp +++ b/rts/Lua/LuaHandle.cpp @@ -73,7 +73,6 @@ bool CLuaHandle::devMode = false; /****************************************************************************** * Callins, functions called by the Engine * - * @module LuaHandle * * This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the changelog. * @@ -523,7 +522,7 @@ bool CLuaHandle::LoadCode(lua_State* L, std::string code, const string& debug) /*** Called when the addon or the game is shutdown. * * @function Shutdown - * @treturn nil + * @return nil */ void CLuaHandle::Shutdown() { @@ -545,8 +544,8 @@ void CLuaHandle::Shutdown() /*** Called when a player issues a UI command e.g. types /foo or /luarules foo. * * @function GotChatMsg - * @string msg - * @number playerID + * @param msg string + * @param playerID number */ bool CLuaHandle::GotChatMsg(const string& msg, int playerID) { @@ -577,7 +576,7 @@ bool CLuaHandle::GotChatMsg(const string& msg, int playerID) /*** Called after `GamePreload` and before `GameStart`. See Lua_SaveLoad. * * @function Load - * @tparam table zipReader + * @param zipReader table */ void CLuaHandle::Load(IArchive* archive) { @@ -661,10 +660,10 @@ void CLuaHandle::GamePreload() /*** Called upon the start of the game. - * - * Is not called when a saved game is loaded. * * @function GameStart + * + * Is not called when a saved game is loaded. */ void CLuaHandle::GameStart() { @@ -686,7 +685,7 @@ void CLuaHandle::GameStart() /*** Called when the game ends * * @function GameOver - * @tparam {number,...} winningAllyTeams list of winning allyTeams, if empty the game result was undecided (like when dropping from an host). + * @param winningAllyTeams number[] list of winning allyTeams, if empty the game result was undecided (like when dropping from an host). */ void CLuaHandle::GameOver(const std::vector& winningAllyTeams) { @@ -713,8 +712,8 @@ void CLuaHandle::GameOver(const std::vector& winningAllyTeams) /*** Called when the game is paused. * * @function GamePaused - * @number playerID - * @bool paused + * @param playerID number + * @param paused boolean */ void CLuaHandle::GamePaused(int playerID, bool paused) { @@ -763,7 +762,7 @@ void CLuaHandle::RunDelayedFunctions(int frameNum) /*** Called for every game simulation frame (30 per second). * * @function GameFrame - * @number frame Starts at frame 1 + * @param frame number Starts at frame 1 */ void CLuaHandle::GameFrame(int frameNum) { @@ -797,7 +796,7 @@ void CLuaHandle::GameFrame(int frameNum) /*** Called at the end of every game simulation frame * * @function GameFramePost - * @number frame Starts at frame 1 + * @param frame number Starts at frame 1 */ void CLuaHandle::GameFramePost(int frameNum) { @@ -821,7 +820,7 @@ void CLuaHandle::GameFramePost(int frameNum) /*** Called once to deliver the gameID * * @function GameID - * @string gameID encoded in hex. + * @param gameID string encoded in hex. */ void CLuaHandle::GameID(const unsigned char* gameID, unsigned int numBytes) { @@ -852,7 +851,7 @@ void CLuaHandle::GameID(const unsigned char* gameID, unsigned int numBytes) /*** Called when a team dies (see `Spring.KillTeam`). * * @function TeamDied - * @number teamID + * @param teamID number */ void CLuaHandle::TeamDied(int teamID) { @@ -875,7 +874,7 @@ void CLuaHandle::TeamDied(int teamID) /*** @function TeamChanged * - * @number teamID + * @param teamID number */ void CLuaHandle::TeamChanged(int teamID) { @@ -899,7 +898,7 @@ void CLuaHandle::TeamChanged(int teamID) /*** Called whenever a player's status changes e.g. becoming a spectator. * * @function PlayerChanged - * @number playerID + * @param playerID number */ void CLuaHandle::PlayerChanged(int playerID) { @@ -923,7 +922,7 @@ void CLuaHandle::PlayerChanged(int playerID) /*** Called whenever a new player joins the game. * * @function PlayerAdded - * @number playerID + * @param playerID number */ void CLuaHandle::PlayerAdded(int playerID) { @@ -947,8 +946,8 @@ void CLuaHandle::PlayerAdded(int playerID) /*** Called whenever a player is removed from the game. * * @function PlayerRemoved - * @number playerID - * @string reason + * @param playerID number + * @param reason string */ void CLuaHandle::PlayerRemoved(int playerID, int reason) { @@ -997,10 +996,10 @@ inline void CLuaHandle::UnitCallIn(const LuaHashString& hs, const CUnit* unit) /*** Called at the moment the unit is created. * * @function UnitCreated - * @number unitID - * @number unitDefID - * @number unitTeam - * @number[opt] builderID + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param builderID number? */ void CLuaHandle::UnitCreated(const CUnit* unit, const CUnit* builder) { @@ -1028,9 +1027,9 @@ void CLuaHandle::UnitCreated(const CUnit* unit, const CUnit* builder) /*** Called at the moment the unit is completed. * * @function UnitFinished - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitFinished(const CUnit* unit) { @@ -1042,12 +1041,12 @@ void CLuaHandle::UnitFinished(const CUnit* unit) /*** Called when a factory finishes construction of a unit. * * @function UnitFromFactory - * @number unitID - * @number unitDefID - * @number unitTeam - * @number factID - * @number factDefID - * @bool userOrders + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param factID number + * @param factDefID number + * @param userOrders boolean */ void CLuaHandle::UnitFromFactory(const CUnit* unit, const CUnit* factory, bool userOrders) @@ -1076,9 +1075,9 @@ void CLuaHandle::UnitFromFactory(const CUnit* unit, /*** Called when a living unit becomes a nanoframe again. * * @function UnitReverseBuilt - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitReverseBuilt(const CUnit* unit) { @@ -1091,12 +1090,12 @@ void CLuaHandle::UnitReverseBuilt(const CUnit* unit) /*** Called when a unit being built starts decaying. * * @function UnitConstructionDecayed - * @number unitID - * @number unitDefID - * @number unitTeam - * @number timeSinceLastBuild - * @number iterationPeriod - * @number part + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param timeSinceLastBuild number + * @param iterationPeriod number + * @param part number */ void CLuaHandle::UnitConstructionDecayed(const CUnit* unit, float timeSinceLastBuild, float iterationPeriod, float part) { @@ -1124,13 +1123,13 @@ void CLuaHandle::UnitConstructionDecayed(const CUnit* unit, float timeSinceLastB /*** Called when a unit is destroyed. * * @function UnitDestroyed - * @number unitID - * @number unitDefID - * @number unitTeam - * @number attackerID - * @number attackerDefID - * @number attackerTeam - * @number weaponDefID + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param attackerID number + * @param attackerDefID number + * @param attackerTeam number + * @param weaponDefID number */ void CLuaHandle::UnitDestroyed(const CUnit* unit, const CUnit* attacker, int weaponDefID) { @@ -1162,10 +1161,10 @@ void CLuaHandle::UnitDestroyed(const CUnit* unit, const CUnit* attacker, int wea /*** Called when a unit is transferred between teams. This is called before `UnitGiven` and in that moment unit is still assigned to the oldTeam. * * @function UnitTaken - * @number unitID - * @number unitDefID - * @number oldTeam - * @number newTeam + * @param unitID integer + * @param unitDefID integer + * @param oldTeam number + * @param newTeam number */ void CLuaHandle::UnitTaken(const CUnit* unit, int oldTeam, int newTeam) { @@ -1191,10 +1190,10 @@ void CLuaHandle::UnitTaken(const CUnit* unit, int oldTeam, int newTeam) /*** Called when a unit is transferred between teams. This is called after `UnitTaken` and in that moment unit is assigned to the newTeam. * * @function UnitGiven - * @number unitID - * @number unitDefID - * @number newTeam - * @number oldTeam + * @param unitID integer + * @param unitDefID integer + * @param newTeam number + * @param oldTeam number */ void CLuaHandle::UnitGiven(const CUnit* unit, int oldTeam, int newTeam) { @@ -1220,9 +1219,9 @@ void CLuaHandle::UnitGiven(const CUnit* unit, int oldTeam, int newTeam) /*** Called when a unit is idle (empty command queue). * * @function UnitIdle - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitIdle(const CUnit* unit) { @@ -1234,13 +1233,13 @@ void CLuaHandle::UnitIdle(const CUnit* unit) /*** Called after when a unit accepts a command, after `AllowCommand` returns true. * * @function UnitCommand - * @number unitID - * @number unitDefID - * @number unitTeam - * @number cmdID - * @tparam table cmdParams - * @tparam cmdOpts options - * @number cmdTag + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param cmdID number + * @param cmdParams table + * @param options CommandOptions + * @param cmdTag number */ void CLuaHandle::UnitCommand(const CUnit* unit, const Command& command, int playerNum, bool fromSynced, bool fromLua) { @@ -1268,13 +1267,13 @@ void CLuaHandle::UnitCommand(const CUnit* unit, const Command& command, int play /*** Called when a unit completes a command. * * @function UnitCmdDone - * @number unitID - * @number unitDefID - * @number unitTeam - * @number cmdID - * @tparam table cmdParams - * @tparam cmdOpts options - * @number cmdTag + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param cmdID number + * @param cmdParams table + * @param options CommandOptions + * @param cmdTag number */ void CLuaHandle::UnitCmdDone(const CUnit* unit, const Command& command) { @@ -1298,16 +1297,16 @@ void CLuaHandle::UnitCmdDone(const CUnit* unit, const Command& command) /*** Called when a unit is damaged (after UnitPreDamaged). * * @function UnitDamaged - * @number unitID - * @number unitDefID - * @number unitTeam - * @number damage - * @number paralyzer - * @number weaponDefID - * @number projectileID - * @number attackerID - * @number attackerDefID - * @number attackerTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param damage number + * @param paralyzer number + * @param weaponDefID number + * @param projectileID number + * @param attackerID number + * @param attackerDefID number + * @param attackerTeam number */ void CLuaHandle::UnitDamaged( const CUnit* unit, @@ -1346,10 +1345,10 @@ void CLuaHandle::UnitDamaged( /*** Called when a unit changes its stun status. * * @function UnitStunned - * @number unitID - * @number unitDefID - * @number unitTeam - * @bool stunned + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param stunned boolean */ void CLuaHandle::UnitStunned( const CUnit* unit, @@ -1374,17 +1373,18 @@ void CLuaHandle::UnitStunned( } -/*** Called when a unit gains experience greater or equal to the minimum limit set by calling `Spring.SetExperienceGrade`. - * - * @function UnitExperience +/*** + * Called when a unit gains experience greater or equal to the minimum limit set by calling `Spring.SetExperienceGrade`. * * Should be called more reliably with small values of experience grade. * - * @number unitID - * @number unitDefID - * @number unitTeam - * @number experience - * @number oldExperience + * @function UnitExperience + * + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param experience number + * @param oldExperience number */ void CLuaHandle::UnitExperience(const CUnit* unit, float oldExperience) { @@ -1412,9 +1412,9 @@ void CLuaHandle::UnitExperience(const CUnit* unit, float oldExperience) /*** Called when a unit's harvestStorage is full (according to its unitDef's entry). * * @function UnitHarvestStorageFull - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitHarvestStorageFull(const CUnit* unit) { @@ -1431,13 +1431,13 @@ void CLuaHandle::UnitHarvestStorageFull(const CUnit* unit) * * See `seismicSignature`. * - * @number x - * @number y - * @number z - * @number strength - * @number allyTeam - * @number unitID - * @number unitDefID + * @param x number + * @param y number + * @param z number + * @param strength number + * @param allyTeam integer + * @param unitID integer + * @param unitDefID integer */ void CLuaHandle::UnitSeismicPing(const CUnit* unit, int allyTeam, const float3& pos, float strength) @@ -1492,16 +1492,16 @@ void CLuaHandle::LosCallIn(const LuaHashString& hs, } -/*** Called when a unit enters radar of an allyteam. - * - * @function UnitEnteredRadar +/*** + * Called when a unit enters radar of an allyteam. * * Also called when a unit enters LOS without any radar coverage. * - * @number unitID - * @number unitTeam - * @number allyTeam - * @number unitDefID + * @function UnitEnteredRadar + * @param unitID integer + * @param unitTeam integer + * @param allyTeam integer + * @param unitDefID integer */ void CLuaHandle::UnitEnteredRadar(const CUnit* unit, int allyTeam) { @@ -1511,16 +1511,16 @@ void CLuaHandle::UnitEnteredRadar(const CUnit* unit, int allyTeam) } -/*** Called when a unit enters LOS of an allyteam. - * - * @function UnitEnteredLos +/*** + * Called when a unit enters LOS of an allyteam. * * Its called after the unit is in LOS, so you can query that unit. * - * @number unitID - * @number unitTeam - * @number allyTeam who's LOS the unit entered. - * @number unitDefID + * @function UnitEnteredLos + * @param unitID integer + * @param unitTeam integer + * @param allyTeam integer who's LOS the unit entered. + * @param unitDefID integer */ void CLuaHandle::UnitEnteredLos(const CUnit* unit, int allyTeam) { @@ -1529,17 +1529,18 @@ void CLuaHandle::UnitEnteredLos(const CUnit* unit, int allyTeam) } -/*** Called when a unit leaves radar of an allyteam. - * - * @function UnitLeftRadar +/*** + * Called when a unit leaves radar of an allyteam. * * Also called when a unit leaves LOS without any radar coverage. - * For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar. + * For widgets, this is called just after a unit leaves radar coverage, so + * widgets cannot get the position of units that left their radar. * - * @number unitID - * @number unitTeam - * @number allyTeam - * @number unitDefID + * @function UnitLeftRadar + * @param unitID integer + * @param unitTeam integer + * @param allyTeam integer + * @param unitDefID integer */ void CLuaHandle::UnitLeftRadar(const CUnit* unit, int allyTeam) { @@ -1549,16 +1550,16 @@ void CLuaHandle::UnitLeftRadar(const CUnit* unit, int allyTeam) } -/*** Called when a unit leaves LOS of an allyteam. - * - * @function UnitLeftLos +/*** + * Called when a unit leaves LOS of an allyteam. * * For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los. * - * @number unitID - * @number unitTeam - * @number allyTeam - * @number unitDefID + * @function UnitLeftLos + * @param unitID integer + * @param unitTeam integer + * @param allyTeam integer + * @param unitDefID integer */ void CLuaHandle::UnitLeftLos(const CUnit* unit, int allyTeam) { @@ -1576,11 +1577,11 @@ void CLuaHandle::UnitLeftLos(const CUnit* unit, int allyTeam) /*** Called when a unit is loaded by a transport. * * @function UnitLoaded - * @number unitID - * @number unitDefID - * @number unitTeam - * @number transportID - * @number transportTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param transportID integer + * @param transportTeam integer */ void CLuaHandle::UnitLoaded(const CUnit* unit, const CUnit* transport) { @@ -1605,14 +1606,14 @@ void CLuaHandle::UnitLoaded(const CUnit* unit, const CUnit* transport) } -/*** Called when a unit is unloaded by a transport. +/***Called when a unit is unloaded by a transport. * * @function UnitUnloaded - * @number unitID - * @number unitDefID - * @number unitTeam - * @number transportID - * @number transportTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param transportID integer + * @param transportTeam integer */ void CLuaHandle::UnitUnloaded(const CUnit* unit, const CUnit* transport) { @@ -1646,9 +1647,9 @@ void CLuaHandle::UnitUnloaded(const CUnit* unit, const CUnit* transport) /*** * * @function UnitEnteredUnderwater - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitEnteredUnderwater(const CUnit* unit) { @@ -1660,9 +1661,9 @@ void CLuaHandle::UnitEnteredUnderwater(const CUnit* unit) /*** * * @function UnitEnteredWater - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitEnteredWater(const CUnit* unit) { @@ -1675,9 +1676,9 @@ void CLuaHandle::UnitEnteredWater(const CUnit* unit) * * @function UnitLeftAir * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitEnteredAir(const CUnit* unit) { @@ -1690,9 +1691,9 @@ void CLuaHandle::UnitEnteredAir(const CUnit* unit) * * @function UnitLeftUnderwater * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitLeftUnderwater(const CUnit* unit) { @@ -1704,9 +1705,9 @@ void CLuaHandle::UnitLeftUnderwater(const CUnit* unit) * * @function UnitLeftWater * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitLeftWater(const CUnit* unit) { @@ -1719,9 +1720,9 @@ void CLuaHandle::UnitLeftWater(const CUnit* unit) * * @function UnitEnteredAir * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitLeftAir(const CUnit* unit) { @@ -1734,9 +1735,9 @@ void CLuaHandle::UnitLeftAir(const CUnit* unit) * * @function UnitCloaked * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitCloaked(const CUnit* unit) { @@ -1749,9 +1750,9 @@ void CLuaHandle::UnitCloaked(const CUnit* unit) * * @function UnitDecloaked * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitDecloaked(const CUnit* unit) { @@ -1761,13 +1762,12 @@ void CLuaHandle::UnitDecloaked(const CUnit* unit) /*** Called when two units collide. - * - * @function UnitUnitCollision * * Both units must be registered with `Script.SetWatchUnit`. * - * @number colliderID - * @number collideeID + * @function UnitUnitCollision + * @param colliderID number + * @param collideeID number */ bool CLuaHandle::UnitUnitCollision(const CUnit* collider, const CUnit* collidee) { @@ -1818,8 +1818,8 @@ bool CLuaHandle::UnitUnitCollision(const CUnit* collider, const CUnit* collidee) * * The unit must be registered with `Script.SetWatchUnit` and the feature registered with `Script.SetWatchFeature`. * - * @number colliderID - * @number collideeID + * @param colliderID number + * @param collideeID number */ bool CLuaHandle::UnitFeatureCollision(const CUnit* collider, const CFeature* collidee) { @@ -1869,9 +1869,9 @@ bool CLuaHandle::UnitFeatureCollision(const CUnit* collider, const CFeature* col * * @function UnitMoveFailed * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitMoveFailed(const CUnit* unit) { @@ -1891,9 +1891,9 @@ void CLuaHandle::UnitMoveFailed(const CUnit* unit) * * @function UnitArrivedAtGoal * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::UnitArrivedAtGoal(const CUnit* unit) { @@ -1908,9 +1908,9 @@ void CLuaHandle::UnitArrivedAtGoal(const CUnit* unit) * * @function RenderUnitDestroyed * - * @number unitID - * @number unitDefID - * @number unitTeam + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer */ void CLuaHandle::RenderUnitDestroyed(const CUnit* unit) { @@ -1946,8 +1946,8 @@ void CLuaHandle::RenderUnitDestroyed(const CUnit* unit) * * @function FeatureCreated * - * @number featureID - * @number allyTeamID + * @param featureID number + * @param allyTeamID number */ void CLuaHandle::FeatureCreated(const CFeature* feature) { @@ -1973,8 +1973,8 @@ void CLuaHandle::FeatureCreated(const CFeature* feature) * * @function FeatureDestroyed * - * @number featureID - * @number allyTeamID + * @param featureID number + * @param allyTeamID number */ void CLuaHandle::FeatureDestroyed(const CFeature* feature) { @@ -2000,15 +2000,15 @@ void CLuaHandle::FeatureDestroyed(const CFeature* feature) * * @function FeatureDamaged * - * @number featureID - * @number featureDefID - * @number featureTeam - * @number damage - * @number weaponDefID - * @number projectileID - * @number attackerID - * @number attackerDefID - * @number attackerTeam + * @param featureID number + * @param featureDefID number + * @param featureTeam number + * @param damage number + * @param weaponDefID number + * @param projectileID number + * @param attackerID number + * @param attackerDefID number + * @param attackerTeam number */ void CLuaHandle::FeatureDamaged( const CFeature* feature, @@ -2056,9 +2056,9 @@ void CLuaHandle::FeatureDamaged( * * Note that weaponDefID is missing if the projectile is spawned as part of a burst, but `Spring.GetProjectileDefID` and `Spring.GetProjectileName` still work in callin scope using proID. * - * @number proID - * @number proOwnerID - * @number weaponDefID + * @param proID number + * @param proOwnerID number + * @param weaponDefID number * */ void CLuaHandle::ProjectileCreated(const CProjectile* p) @@ -2103,9 +2103,9 @@ void CLuaHandle::ProjectileCreated(const CProjectile* p) /*** Called when the projectile is destroyed. * * @function ProjectileDestroyed - * @number proID - * @number ownerID - * @number proWeaponDefID + * @param proID number + * @param ownerID number + * @param proWeaponDefID number */ void CLuaHandle::ProjectileDestroyed(const CProjectile* p) { @@ -2157,13 +2157,13 @@ void CLuaHandle::ProjectileDestroyed(const CProjectile* p) * * @function Explosion * - * @number weaponDefID - * @number px - * @number py - * @number pz - * @number attackerID - * @number projectileID - * @return bool noGfx if then no graphical effects are drawn by the engine for this explosion. + * @param weaponDefID number + * @param px number + * @param py number + * @param pz number + * @param attackerID number + * @param projectileID number + * @return boolean noGfx if then no graphical effects are drawn by the engine for this explosion. */ bool CLuaHandle::Explosion(int weaponDefID, int projectileID, const float3& pos, const CUnit* owner) { @@ -2212,12 +2212,12 @@ bool CLuaHandle::Explosion(int weaponDefID, int projectileID, const float3& pos, * * @function StockpileChanged * - * @number unitID - * @number unitDefID - * @number unitTeam - * @number weaponNum - * @number oldCount - * @number newCount + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param weaponNum integer + * @param oldCount integer + * @param newCount integer */ void CLuaHandle::StockpileChanged(const CUnit* unit, const CWeapon* weapon, int oldCount) @@ -2246,8 +2246,8 @@ void CLuaHandle::StockpileChanged(const CUnit* unit, /*** Receives messages from unsynced sent via `Spring.SendLuaRulesMsg` or `Spring.SendLuaUIMsg`. * * @function RecvLuaMsg - * @string msg - * @number playerID + * @param msg string + * @param playerID number */ bool CLuaHandle::RecvLuaMsg(const string& msg, int playerID) { @@ -2327,7 +2327,7 @@ void CLuaHandle::HandleLuaMsg(int playerID, int script, int mode, const std::vec /*** Called when a chat command '/save' or '/savegame' is received. * * @function Save - * @tparam table zip a userdatum representing the savegame zip file. See Lua_SaveLoad. + * @param zip table a userdatum representing the savegame zip file. See Lua_SaveLoad. */ void CLuaHandle::Save(zipFile archive) { @@ -2353,10 +2353,10 @@ void CLuaHandle::Save(zipFile archive) /*** Called when the unsynced copy of the height-map is altered. * * @function UnsyncedHeightMapUpdate - * @treturn x1 - * @treturn z1 - * @treturn x2 - * @treturn z2 + * @return number x1 + * @return number z1 + * @return number x2 + * @return number z2 */ void CLuaHandle::UnsyncedHeightMapUpdate(const SRectangle& rect) { @@ -2380,7 +2380,7 @@ void CLuaHandle::UnsyncedHeightMapUpdate(const SRectangle& rect) /*** Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up. * * @function Update - * @number dt the time since the last update. + * @param dt number the time since the last update. */ void CLuaHandle::Update() { @@ -2399,8 +2399,8 @@ void CLuaHandle::Update() /*** Called whenever the window is resized. * * @function ViewResize - * @number viewSizeX - * @number viewSizeY + * @param viewSizeX number + * @param viewSizeY number */ void CLuaHandle::ViewResize() { @@ -2475,8 +2475,8 @@ void CLuaHandle::SunChanged() /*** Used to set the default command when a unit is selected. First parameter is the type of the object pointed at (either "unit or "feature") and the second is its unitID or featureID respectively. * * @function DefaultCommand - * @string type "unit" | "feature" - * @int id unitID | featureID + * @param type string "unit" | "feature" + * @param id integer unitID | featureID */ bool CLuaHandle::DefaultCommand(const CUnit* unit, const CFeature* feature, int& cmd) @@ -2677,10 +2677,10 @@ DRAW_CALLIN(DrawShadowFeaturesLua) * Each call has a different permutation of values for drawAboveWater, drawBelowWater, drawReflection, and drawRefraction. * * @function DrawWorldPreParticles - * @bool drawAboveWater - * @bool drawBelowWater - * @bool drawReflection - * @bool drawRefraction + * @param drawAboveWater boolean + * @param drawBelowWater boolean + * @param drawReflection boolean + * @param drawRefraction boolean */ void CLuaHandle::DrawWorldPreParticles(bool drawAboveWater, bool drawBelowWater, bool drawReflection, bool drawRefraction) { @@ -2723,8 +2723,8 @@ inline void CLuaHandle::DrawScreenCommon(const LuaHashString& cmdStr) /*** Also available to LuaMenu. * * @function DrawScreen - * @number viewSizeX - * @number viewSizeY + * @param viewSizeX number + * @param viewSizeY number */ void CLuaHandle::DrawScreen() { @@ -2739,8 +2739,8 @@ void CLuaHandle::DrawScreen() /*** * @function DrawScreenEffects - * @number viewSizeX - * @number viewSizeY + * @param viewSizeX number + * @param viewSizeY number */ void CLuaHandle::DrawScreenEffects() { @@ -2756,8 +2756,8 @@ void CLuaHandle::DrawScreenEffects() /*** Similar to DrawScreenEffects, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI). * * @function DrawScreenPost - * @number viewSizeX - * @number viewSizeY + * @param viewSizeX number + * @param viewSizeY number */ void CLuaHandle::DrawScreenPost() { @@ -2773,8 +2773,8 @@ void CLuaHandle::DrawScreenPost() /*** * * @function DrawInMinimap - * @number sx relative to the minimap's position and scale. - * @number sy relative to the minimap's position and scale. + * @param sx number relative to the minimap's position and scale. + * @param sy number relative to the minimap's position and scale. */ void CLuaHandle::DrawInMiniMap() { @@ -2801,8 +2801,8 @@ void CLuaHandle::DrawInMiniMap() /*** * * @function DrawInMinimapBackground - * @number sx relative to the minimap's position and scale. - * @number sy relative to the minimap's position and scale. + * @param sx number relative to the minimap's position and scale. + * @param sy number relative to the minimap's position and scale. */ void CLuaHandle::DrawInMiniMapBackground() { @@ -2878,7 +2878,7 @@ void CLuaHandle::DrawAlphaFeaturesLua(bool drawReflection, bool drawRefraction) * Can give an ETA about catching up with simulation for mid-game join players. * * @function GameProgress - * @int serverFrameNum + * @param serverFrameNum integer */ void CLuaHandle::GameProgress(int frameNum) { @@ -2949,12 +2949,12 @@ bool CLuaHandle::KeyMapChanged() /*** Key Modifier Params * - * @table mods + * @class KeyModifiers * - * @tparam bool right Right mouse key pressed - * @tparam bool alt Alt key pressed - * @tparam bool ctrl Ctrl key pressed - * @tparam bool shift Shift key pressed + * @field right boolean Right mouse key pressed + * @field alt boolean Alt key pressed + * @field ctrl boolean Ctrl key pressed + * @field shift boolean Shift key pressed */ @@ -2964,14 +2964,14 @@ bool CLuaHandle::KeyMapChanged() * * Return true if you don't want other callins or the engine to also receive this keypress. A list of key codes can be seen at the SDL wiki. * - * @number keyCode - * @tparam mods mods - * @bool isRepeat If you want an action to occur only once check for isRepeat == false. - * @bool label the name of the key - * @number utf32char (deprecated) always 0 - * @number scanCode - * @tparam table actionList the list of actions for this keypress - * @treturn boolean halt whether to halt the chain for consumers of the keypress + * @param keyCode number + * @param mods KeyModifiers + * @param isRepeat boolean If you want an action to occur only once check for isRepeat == false. + * @param label boolean the name of the key + * @param utf32char number (deprecated) always 0 + * @param scanCode number + * @param actionList table the list of actions for this keypress + * @return boolean halt whether to halt the chain for consumers of the keypress */ bool CLuaHandle::KeyPress(int keyCode, int scanCode, bool isRepeat) { @@ -3030,14 +3030,14 @@ bool CLuaHandle::KeyPress(int keyCode, int scanCode, bool isRepeat) * * @function KeyRelease * - * @number keyCode - * @tparam mods mods - * @bool label the name of the key - * @number utf32char (deprecated) always 0 - * @number scanCode - * @tparam table actionList the list of actions for this keyrelease + * @param keyCode number + * @param mods KeyModifiers + * @param label boolean the name of the key + * @param utf32char number (deprecated) always 0 + * @param scanCode number + * @param actionList table the list of actions for this keyrelease * - * @treturn bool + * @return boolean */ bool CLuaHandle::KeyRelease(int keyCode, int scanCode) { @@ -3091,7 +3091,7 @@ bool CLuaHandle::KeyRelease(int keyCode, int scanCode) * * @function TextInput * - * @string utf8char + * @param utf8char string */ bool CLuaHandle::TextInput(const std::string& utf8) { @@ -3119,9 +3119,9 @@ bool CLuaHandle::TextInput(const std::string& utf8) * * @function TextEditing * - * @string utf8 - * @number start - * @number length + * @param utf8 string + * @param start number + * @param length number */ bool CLuaHandle::TextEditing(const std::string& utf8, unsigned int start, unsigned int length) { @@ -3150,10 +3150,10 @@ bool CLuaHandle::TextEditing(const std::string& utf8, unsigned int start, unsign * The button parameter supports up to 7 buttons. Must return true for `MouseRelease` and other functions to be called. * * @function MousePress - * @number x - * @number y - * @number button - * @treturn boolean becomeMouseOwner + * @param x number + * @param y number + * @param button number + * @return boolean becomeMouseOwner */ bool CLuaHandle::MousePress(int x, int y, int button) { @@ -3184,10 +3184,10 @@ bool CLuaHandle::MousePress(int x, int y, int button) * * Please note that in order to have Spring call `Spring.MouseRelease`, you need to have a `Spring.MousePress` call-in in the same addon that returns true. * - * @number x - * @number y - * @number button - * @treturn boolean becomeMouseOwner + * @param x number + * @param y number + * @param button number + * @return boolean becomeMouseOwner */ void CLuaHandle::MouseRelease(int x, int y, int button) { @@ -3211,11 +3211,11 @@ void CLuaHandle::MouseRelease(int x, int y, int button) * * @function MouseMove * - * @number x final x position - * @number y final y position - * @number dx distance travelled in x - * @number dy distance travelled in y - * @number button + * @param x number final x position + * @param y number final y position + * @param dx number distance travelled in x + * @param dy number distance travelled in y + * @param button number */ bool CLuaHandle::MouseMove(int x, int y, int dx, int dy, int button) { @@ -3246,8 +3246,8 @@ bool CLuaHandle::MouseMove(int x, int y, int dx, int dy, int button) * * @function MouseWheel * - * @bool up the direction - * @number value the amount travelled + * @param up boolean the direction + * @param value number the amount travelled */ bool CLuaHandle::MouseWheel(bool up, float value) { @@ -3275,8 +3275,8 @@ bool CLuaHandle::MouseWheel(bool up, float value) * * Must return true for `Mouse*` events and `Spring.GetToolTip` to be called. * - * @number x - * @number y + * @param x number + * @param y number * @return boolean isAbove */ bool CLuaHandle::IsAbove(int x, int y) @@ -3303,8 +3303,8 @@ bool CLuaHandle::IsAbove(int x, int y) /*** Called when `Spring.IsAbove` returns true. * * @function GetTooltip - * @number x - * @number y + * @param x number + * @param y number * @return string tooltip */ string CLuaHandle::GetTooltip(int x, int y) @@ -3328,25 +3328,11 @@ string CLuaHandle::GetTooltip(int x, int y) return retval; } - -/*** Parameters for command options - * - * @table cmdOpts - * - * @int coded - * @bool alt - * @bool ctrl - * @bool shift - * @bool right - * @bool meta - * @bool internal - */ - /*** Called when a command is issued. * * @function ActiveCommandChanged - * @tparam nil|number cmdID - * @tparam nil|number cmdType + * @param cmdId integer? + * @param cmdType integer? */ void CLuaHandle::ActiveCommandChanged(const SCommandDescription* cmdDesc) { @@ -3371,10 +3357,10 @@ void CLuaHandle::ActiveCommandChanged(const SCommandDescription* cmdDesc) /*** Called when a command is issued. * * @function CommandNotify - * @int cmdID - * @tparam table cmdParams - * @tparam cmdOpts options - * @treturn boolean Returning true deletes the command and does not send it through the network. + * @param cmdID integer + * @param cmdParams table + * @param options CommandOptions + * @return boolean Returning true deletes the command and does not send it through the network. */ bool CLuaHandle::CommandNotify(const Command& cmd) { @@ -3407,8 +3393,8 @@ bool CLuaHandle::CommandNotify(const Command& cmd) /*** Called when text is entered into the console (e.g. `Spring.Echo`). * * @function AddConsoleLine - * @string msg - * @int priority + * @param msg string + * @param priority integer */ bool CLuaHandle::AddConsoleLine(const string& msg, const string& section, int level) { @@ -3430,7 +3416,7 @@ bool CLuaHandle::AddConsoleLine(const string& msg, const string& section, int le /*** Called when a unit is added to or removed from a control group. * * @function GroupChanged - * @number groupID + * @param groupID number */ bool CLuaHandle::GroupChanged(int groupID) { @@ -3451,11 +3437,11 @@ bool CLuaHandle::GroupChanged(int groupID) /*** * @function WorldTooltip - * @string ttType "unit" | "feature" | "ground" | "selection" - * @number data1 unitID | featureID | posX - * @number[opt] data2 posY - * @number[opt] data3 posZ - * @treturn string newTooltip + * @param ttType string "unit" | "feature" | "ground" | "selection" + * @param data1 number unitID | featureID | posX + * @param data2 number? posY + * @param data3 number? posZ + * @return string newTooltip */ string CLuaHandle::WorldTooltip(const CUnit* unit, const CFeature* feature, @@ -3504,14 +3490,14 @@ string CLuaHandle::WorldTooltip(const CUnit* unit, /*** * * @function MapDrawCmd - * @number playerID - * @string type "point" | "line" | "erase" - * @number posX - * @number posY - * @number posZ - * @tparam string|number data4 point: label, erase: radius, line: pos2X - * @number[opt] pos2Y when type is line - * @number[opt] pos2Z when type is line + * @param playerID number + * @param type string "point" | "line" | "erase" + * @param posX number + * @param posY number + * @param posZ number + * @param data4 string|number point: label, erase: radius, line: pos2X + * @param pos2Y number? when type is line + * @param pos2Z number? when type is line */ bool CLuaHandle::MapDrawCmd(int playerID, int type, const float3* pos0, @@ -3575,11 +3561,11 @@ bool CLuaHandle::MapDrawCmd(int playerID, int type, /*** * * @function GameSetup - * @string state - * @bool ready - * @tparam table playerStates - * @treturn bool success - * @treturn bool newReady + * @param state string + * @param ready boolean + * @param playerStates table + * @return boolean success + * @return boolean newReady */ bool CLuaHandle::GameSetup(const string& state, bool& ready, const std::vector< std::pair >& playerStates) @@ -3625,8 +3611,8 @@ bool CLuaHandle::GameSetup(const string& state, bool& ready, /*** @function RecvSkirmishAIMessage * - * @int aiTeam - * @string dataStr + * @param aiTeam integer + * @param dataStr string */ const char* CLuaHandle::RecvSkirmishAIMessage(int aiTeam, const char* inData, int inSize, size_t* outSize) { @@ -3671,9 +3657,9 @@ const char* CLuaHandle::RecvSkirmishAIMessage(int aiTeam, const char* inData, in /*** Called when a Pr-downloader download is queued * * @function DownloadQueued - * @number id - * @string name - * @string type + * @param id number + * @param name string + * @param type string */ void CLuaHandle::DownloadQueued(int ID, const string& archiveName, const string& archiveType) { @@ -3699,7 +3685,7 @@ void CLuaHandle::DownloadQueued(int ID, const string& archiveName, const string& /*** Called when a Pr-downloader download is started via VFS.DownloadArchive. * * @function DownloadStarted - * @number id + * @param id number */ void CLuaHandle::DownloadStarted(int ID) { @@ -3722,7 +3708,7 @@ void CLuaHandle::DownloadStarted(int ID) /*** Called when a Pr-downloader download finishes successfully. * * @function DownloadFinished - * @number id + * @param id number */ void CLuaHandle::DownloadFinished(int ID) { @@ -3745,8 +3731,8 @@ void CLuaHandle::DownloadFinished(int ID) /*** Called when a Pr-downloader download fails to complete. * * @function DownloadFailed - * @number id - * @number errorID + * @param id number + * @param errorID number */ void CLuaHandle::DownloadFailed(int ID, int errorID) { @@ -3770,9 +3756,9 @@ void CLuaHandle::DownloadFailed(int ID, int errorID) /*** Called incrementally during a Pr-downloader download. * * @function DownloadProgress - * @number id - * @number downloaded - * @number total + * @param id number + * @param downloaded number + * @param total number */ void CLuaHandle::DownloadProgress(int ID, long downloaded, long total) { diff --git a/rts/Lua/LuaHandleSynced.cpp b/rts/Lua/LuaHandleSynced.cpp index 426dad323a..c5eb895f8d 100644 --- a/rts/Lua/LuaHandleSynced.cpp +++ b/rts/Lua/LuaHandleSynced.cpp @@ -166,7 +166,6 @@ bool CUnsyncedLuaHandle::Init(std::string code, const std::string& file) /****************************************************************************** * Callins, functions called by the Engine (Synced) * - * @module LuaHandleSynced * @see rts/Lua/LuaHandleSynced.cpp */ @@ -179,9 +178,9 @@ bool CUnsyncedLuaHandle::Init(std::string code, const std::string& file) /*** Receives data sent via `SendToUnsynced` callout. * * @function RecvFromSynced - * @tparam any arg1 - * @tparam any arg2 - * @tparam any argn + * @param arg1 any + * @param arg2 any + * @param argn any */ void CUnsyncedLuaHandle::RecvFromSynced(lua_State* srcState, int args) { @@ -212,9 +211,9 @@ void CUnsyncedLuaHandle::RecvFromSynced(lua_State* srcState, int args) /*** For custom rendering of units * * @function DrawUnit - * @number unitID - * @number drawMode - * @treturn bool suppressEngineDraw + * @param unitID integer + * @param drawMode number + * @return boolean suppressEngineDraw */ bool CUnsyncedLuaHandle::DrawUnit(const CUnit* unit) { @@ -248,9 +247,9 @@ bool CUnsyncedLuaHandle::DrawUnit(const CUnit* unit) /*** For custom rendering of features * * @function DrawFeature - * @number featureID - * @number drawMode - * @treturn bool suppressEngineDraw + * @param featureID integer + * @param drawMode number + * @return boolean suppressEngineDraw */ bool CUnsyncedLuaHandle::DrawFeature(const CFeature* feature) { @@ -283,10 +282,10 @@ bool CUnsyncedLuaHandle::DrawFeature(const CFeature* feature) /*** For custom rendering of shields. * * @function DrawShield - * @number featureID - * @number weaponID - * @number drawMode - * @treturn bool suppressEngineDraw + * @param featureID integer + * @param weaponID integer + * @param drawMode number + * @return boolean suppressEngineDraw */ bool CUnsyncedLuaHandle::DrawShield(const CUnit* unit, const CWeapon* weapon) { @@ -321,9 +320,9 @@ bool CUnsyncedLuaHandle::DrawShield(const CUnit* unit, const CWeapon* weapon) /*** For custom rendering of weapon (& other) projectiles * * @function DrawProjectile - * @number projectileID - * @number drawMode - * @treturn bool suppressEngineDraw + * @param projectileID integer + * @param drawMode number + * @return boolean suppressEngineDraw */ bool CUnsyncedLuaHandle::DrawProjectile(const CProjectile* projectile) { @@ -358,9 +357,9 @@ bool CUnsyncedLuaHandle::DrawProjectile(const CProjectile* projectile) /*** * * @function DrawMaterial - * @number uuid - * @number drawMode - * @treturn bool suppressEngineDraw + * @param uuid number + * @param drawMode number + * @return boolean suppressEngineDraw */ bool CUnsyncedLuaHandle::DrawMaterial(const LuaMaterial* material) { @@ -566,14 +565,14 @@ bool CSyncedLuaHandle::SyncedActionFallback(const std::string& msg, int playerID /*** Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). * * @function CommandFallback - * @number unitID - * @number unitDefID - * @number unitTeam - * @number cmdID - * @tparam {number,...} cmdParams - * @tparam cmdOptions cmdOptions - * @number cmdTag - * @treturn boolean whether to remove the command from the queue + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param cmdID integer + * @param cmdParams number[] + * @param cmdOptions CommandOptions + * @param cmdTag number + * @return boolean whether to remove the command from the queue */ bool CSyncedLuaHandle::CommandFallback(const CUnit* unit, const Command& cmd) { @@ -602,16 +601,16 @@ bool CSyncedLuaHandle::CommandFallback(const CUnit* unit, const Command& cmd) * * The queue remains untouched when a command is blocked, whether it would be queued or replace the queue. * - * @number unitID - * @number unitDefID - * @number unitTeam - * @number cmdID - * @tparam {number,...} cmdParams - * @tparam cmdOptions cmdOptions - * @number cmdTag - * @bool synced - * @bool fromLua - * @treturn bool whether it should be let into the queue. + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param cmdID integer + * @param cmdParams number[] + * @param cmdOptions CommandOptions + * @param cmdTag number + * @param synced boolean + * @param fromLua boolean + * @return boolean whether it should be let into the queue. */ bool CSyncedLuaHandle::AllowCommand(const CUnit* unit, const Command& cmd, int playerNum, bool fromSynced, bool fromLua) { @@ -643,14 +642,14 @@ bool CSyncedLuaHandle::AllowCommand(const CUnit* unit, const Command& cmd, int p /*** Called just before unit is created. * * @function AllowUnitCreation - * @number unitDefID - * @number builderID - * @number builderTeam - * @number x - * @number y - * @number z - * @number facing - * @treturn bool allow, bool dropOrder + * @param unitDefID integer + * @param builderID integer + * @param builderTeam integer + * @param x number + * @param y number + * @param z number + * @param facing number + * @return boolean allow, boolean dropOrder */ std::pair CSyncedLuaHandle::AllowUnitCreation( const UnitDef* unitDef, @@ -690,12 +689,12 @@ std::pair CSyncedLuaHandle::AllowUnitCreation( /*** Called just before a unit is transferred to a different team. * * @function AllowUnitTransfer - * @number unitID - * @number unitDefID - * @number oldTeam - * @number newTeam - * @bool capture - * @treturn bool whether or not the transfer is permitted. + * @param unitID integer + * @param unitDefID integer + * @param oldTeam integer + * @param newTeam integer + * @param capture boolean + * @return boolean whether or not the transfer is permitted. */ bool CSyncedLuaHandle::AllowUnitTransfer(const CUnit* unit, int newTeam, bool capture) { @@ -727,12 +726,12 @@ bool CSyncedLuaHandle::AllowUnitTransfer(const CUnit* unit, int newTeam, bool ca /*** Called just before a unit progresses its build percentage. * * @function AllowUnitBuildStep - * @number builderID - * @number builderTeam - * @number unitID - * @number unitDefID - * @number part - * @treturn bool whether or not the build makes progress. + * @param builderID integer + * @param builderTeam integer + * @param unitID integer + * @param unitDefID integer + * @param part number + * @return boolean whether or not the build makes progress. */ bool CSyncedLuaHandle::AllowUnitBuildStep(const CUnit* builder, const CUnit* unit, float part) { @@ -764,12 +763,12 @@ bool CSyncedLuaHandle::AllowUnitBuildStep(const CUnit* builder, const CUnit* uni /*** * * @function AllowUnitCaptureStep - * @number builderID - * @number builderTeam - * @number unitID - * @number unitDefID - * @number part - * @treturn bool whether or not the capture makes progress. + * @param builderID integer + * @param builderTeam integer + * @param unitID integer + * @param unitDefID integer + * @param part number + * @return boolean whether or not the capture makes progress. */ bool CSyncedLuaHandle::AllowUnitCaptureStep(const CUnit* builder, const CUnit* unit, float part) { @@ -801,13 +800,13 @@ bool CSyncedLuaHandle::AllowUnitCaptureStep(const CUnit* builder, const CUnit* u /*** * * @function AllowUnitTransport - * @number transporterID - * @number transporterUnitDefID - * @number transporterTeam - * @number transporteeID - * @number transporteeUnitDefID - * @number transporteeTeam - * @treturn bool whether or not the transport is allowed + * @param transporterID integer + * @param transporterUnitDefID integer + * @param transporterTeam integer + * @param transporteeID integer + * @param transporteeUnitDefID integer + * @param transporteeTeam integer + * @return boolean whether or not the transport is allowed */ bool CSyncedLuaHandle::AllowUnitTransport(const CUnit* transporter, const CUnit* transportee) { @@ -839,16 +838,16 @@ bool CSyncedLuaHandle::AllowUnitTransport(const CUnit* transporter, const CUnit* /*** * * @function AllowUnitTransportLoad - * @number transporterID - * @number transporterUnitDefID - * @number transporterTeam - * @number transporteeID - * @number transporteeUnitDefID - * @number transporteeTeam - * @number x - * @number y - * @number z - * @treturn bool whether or not the transport load is allowed + * @param transporterID integer + * @param transporterUnitDefID integer + * @param transporterTeam integer + * @param transporteeID integer + * @param transporteeUnitDefID integer + * @param transporteeTeam integer + * @param x number + * @param y number + * @param z number + * @return boolean whether or not the transport load is allowed */ bool CSyncedLuaHandle::AllowUnitTransportLoad( const CUnit* transporter, @@ -889,16 +888,16 @@ bool CSyncedLuaHandle::AllowUnitTransportLoad( /*** * * @function AllowUnitTransportUnload - * @number transporterID - * @number transporterUnitDefID - * @number transporterTeam - * @number transporteeID - * @number transporteeUnitDefID - * @number transporteeTeam - * @number x - * @number y - * @number z - * @treturn bool whether or not the transport unload is allowed + * @param transporterID integer + * @param transporterUnitDefID integer + * @param transporterTeam integer + * @param transporteeID integer + * @param transporteeUnitDefID integer + * @param transporteeTeam integer + * @param x number + * @param y number + * @param z number + * @return boolean whether or not the transport unload is allowed */ bool CSyncedLuaHandle::AllowUnitTransportUnload( const CUnit* transporter, @@ -937,9 +936,9 @@ bool CSyncedLuaHandle::AllowUnitTransportUnload( /*** * * @function AllowUnitCloak - * @number unitID - * @number[opt] enemyID - * @treturn bool whether unit is allowed to cloak + * @param unitID integer + * @param enemyID integer? + * @return boolean whether unit is allowed to cloak */ bool CSyncedLuaHandle::AllowUnitCloak(const CUnit* unit, const CUnit* enemy) { @@ -973,10 +972,10 @@ bool CSyncedLuaHandle::AllowUnitCloak(const CUnit* unit, const CUnit* enemy) /*** * * @function AllowUnitCloak - * @number unitID - * @number[opt] objectID - * @number[opt] weaponNum - * @treturn bool whether unit is allowed to decloak + * @param unitID integer + * @param objectID integer? + * @param weaponNum number? + * @return boolean whether unit is allowed to decloak */ bool CSyncedLuaHandle::AllowUnitDecloak(const CUnit* unit, const CSolidObject* object, const CWeapon* weapon) { @@ -1017,9 +1016,9 @@ bool CSyncedLuaHandle::AllowUnitDecloak(const CUnit* unit, const CSolidObject* o /*** * * @function AllowUnitKamikaze - * @number unitID - * @number targetID - * @treturn bool whether unit is allowed to selfd + * @param unitID integer + * @param targetID integer + * @return boolean whether unit is allowed to selfd */ bool CSyncedLuaHandle::AllowUnitKamikaze(const CUnit* unit, const CUnit* target, bool allowed) { @@ -1047,12 +1046,12 @@ bool CSyncedLuaHandle::AllowUnitKamikaze(const CUnit* unit, const CUnit* target, /*** Called just before feature is created. * * @function AllowFeatureCreation - * @number featureDefID - * @number teamID - * @number x - * @number y - * @number z - * @treturn bool whether or not the creation is permitted + * @param featureDefID integer + * @param teamID integer + * @param x number + * @param y number + * @param z number + * @return boolean whether or not the creation is permitted */ bool CSyncedLuaHandle::AllowFeatureCreation(const FeatureDef* featureDef, int teamID, const float3& pos) { @@ -1091,13 +1090,13 @@ bool CSyncedLuaHandle::AllowFeatureCreation(const FeatureDef* featureDef, int te * Eg. for a 30 workertime builder, that's a build power of 1 per frame. * For a 50 buildtime feature reclaimed by this builder, part will be 100/-50(/1) = -2%, or -0.02 numerically. * - * @number builderID - * @number builderTeam - * @number featureID - * @number featureDefID - * @number part + * @param builderID integer + * @param builderTeam integer + * @param featureID integer + * @param featureDefID integer + * @param part number * - * @treturn bool whether or not the change is permitted + * @return boolean whether or not the change is permitted */ bool CSyncedLuaHandle::AllowFeatureBuildStep(const CUnit* builder, const CFeature* feature, float part) { @@ -1129,10 +1128,10 @@ bool CSyncedLuaHandle::AllowFeatureBuildStep(const CUnit* builder, const CFeatur /*** Called when a team sets the sharing level of a resource. * * @function AllowResourceLevel - * @number teamID - * @string res - * @number level - * @treturn bool whether or not the sharing level is permitted + * @param teamID integer + * @param res string + * @param level number + * @return boolean whether or not the sharing level is permitted */ bool CSyncedLuaHandle::AllowResourceLevel(int teamID, const std::string& type, float level) { @@ -1162,11 +1161,11 @@ bool CSyncedLuaHandle::AllowResourceLevel(int teamID, const std::string& type, f /*** Called just before resources are transferred between players. * * @function AllowResourceTransfer - * @number oldTeamID - * @number newTeamID - * @string res - * @number amount - * @treturn bool whether or not the transfer is permitted. + * @param oldTeamID integer + * @param newTeamID integer + * @param res string + * @param amount number + * @return boolean whether or not the transfer is permitted. */ bool CSyncedLuaHandle::AllowResourceTransfer(int oldTeam, int newTeam, const char* type, float amount) { @@ -1197,11 +1196,11 @@ bool CSyncedLuaHandle::AllowResourceTransfer(int oldTeam, int newTeam, const cha /*** Determines if this unit can be controlled directly in FPS view. * * @function AllowDirectUnitControl - * @number unitID - * @number unitDefID - * @number unitTeam - * @number playerID - * @treturn bool allow + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param playerID integer + * @return boolean allow */ bool CSyncedLuaHandle::AllowDirectUnitControl(int playerID, const CUnit* unit) { @@ -1233,9 +1232,9 @@ bool CSyncedLuaHandle::AllowDirectUnitControl(int playerID, const CUnit* unit) * * @function AllowBuilderHoldFire * - * @number unitID - * @number unitDefID - * @number action one of following: + * @param unitID integer + * @param unitDefID integer + * @param action number one of following: * * -1 Build * CMD.REPAIR Repair @@ -1244,7 +1243,7 @@ bool CSyncedLuaHandle::AllowDirectUnitControl(int playerID, const CUnit* unit) * CMD.RESURRECT Resurrect * CMD.CAPTURE Capture * - * @treturn bool actionAllowed + * @return boolean actionAllowed */ bool CSyncedLuaHandle::AllowBuilderHoldFire(const CUnit* unit, int action) { @@ -1285,17 +1284,17 @@ bool CSyncedLuaHandle::AllowBuilderHoldFire(const CUnit* unit, int action) * 3 - the player failed to load. * The default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox. * - * @number playerID - * @number teamID - * @number readyState - * @number clampedX - * @number clampedY - * @number clampedZ - * @number rawX - * @number rawY - * @number rawZ - * - * @treturn bool allow + * @param playerID integer + * @param teamID integer + * @param readyState number + * @param clampedX number + * @param clampedY number + * @param clampedZ number + * @param rawX number + * @param rawY number + * @param rawZ number + * + * @return boolean allow */ bool CSyncedLuaHandle::AllowStartPosition(int playerID, int teamID, unsigned char readyState, const float3& clampedPos, const float3& rawPickPos) { @@ -1333,12 +1332,12 @@ bool CSyncedLuaHandle::AllowStartPosition(int playerID, int teamID, unsigned cha * * @function MoveCtrlNotify * - * @number unitID - * @number unitDefID - * @number unitTeam - * @number data was supposed to indicate the type of notification but currently never has a value other than 1 ("unit hit the ground"). + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param data number was supposed to indicate the type of notification but currently never has a value other than 1 ("unit hit the ground"). * - * @treturn bool whether or not the unit should remain script-controlled (false) or return to engine controlled movement (true). + * @return boolean whether or not the unit should remain script-controlled (false) or return to engine controlled movement (true). */ bool CSyncedLuaHandle::MoveCtrlNotify(const CUnit* unit, int data) { @@ -1370,13 +1369,13 @@ bool CSyncedLuaHandle::MoveCtrlNotify(const CUnit* unit, int data) /*** Called when pre-building terrain levelling terraforms are completed (c.f. levelGround) * * @function TerraformComplete - * @number unitID - * @number unitDefID - * @number unitTeam - * @number buildUnitID - * @number buildUnitDefID - * @number buildUnitTeam - * @treturn bool if true the current build order is terminated + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param buildUnitID integer + * @param buildUnitDefID integer + * @param buildUnitTeam integer + * @return boolean if true the current build order is terminated */ bool CSyncedLuaHandle::TerraformComplete(const CUnit* unit, const CUnit* build) { @@ -1435,16 +1434,16 @@ bool CSyncedLuaHandle::TerraformComplete(const CUnit* unit, const CUnit* build) * 1st is stored under *newDamage if newDamage != NULL * 2nd is stored under *impulseMult if impulseMult != NULL * - * @number unitID - * @number unitDefID - * @number unitTeam - * @number damage - * @bool paralyzer - * @number[opt] weaponDefID Synced Only - * @number[opt] projectileID Synced Only - * @number[opt] attackerID Synced Only - * @number[opt] attackerDefID Synced Only - * @number[opt] attackerTeam Synced Only + * @param unitID integer + * @param unitDefID integer + * @param unitTeam integer + * @param damage number + * @param paralyzer boolean + * @param weaponDefID integer? Synced Only + * @param projectileID integer? Synced Only + * @param attackerID integer? Synced Only + * @param attackerDefID integer? Synced Only + * @param attackerTeam integer? Synced Only * * @return number newDamage, number impulseMult */ @@ -1527,17 +1526,17 @@ bool CSyncedLuaHandle::UnitPreDamaged( * * Allows fine control over how much damage and impulse is applied. * - * @number featureID - * @number featureDefID - * @number featureTeam - * @number damage - * @number weaponDefID - * @number projectileID - * @number attackerID - * @number attackerDefID - * @number attackerTeam - * @treturn number newDamage - * @treturn number impulseMult + * @param featureID integer + * @param featureDefID integer + * @param featureTeam integer + * @param damage number + * @param weaponDefID integer + * @param projectileID integer + * @param attackerID integer + * @param attackerDefID integer + * @param attackerTeam integer + * @return number newDamage + * @return number impulseMult */ bool CSyncedLuaHandle::FeaturePreDamaged( const CFeature* feature, @@ -1610,21 +1609,21 @@ bool CSyncedLuaHandle::FeaturePreDamaged( * * If the weapon is a hitscan type (BeamLaser or LightningCanon) then proID is nil and beamEmitterWeaponNum and beamEmitterUnitID are populated instead. * - * @number projectileID - * @number projectileOwnerID - * @number shieldWeaponNum - * @number shieldCarrierID - * @bool bounceProjectile - * @number beamEmitterWeaponNum - * @number beamEmitterUnitID - * @number startX - * @number startY - * @number startZ - * @number hitX - * @number hitY - * @number hitZ - * - * @treturn bool if true the gadget handles the collision event and the engine does not remove the projectile + * @param projectileID integer + * @param projectileOwnerID integer + * @param shieldWeaponNum integer + * @param shieldCarrierID integer + * @param bounceProjectile boolean + * @param beamEmitterWeaponNum integer + * @param beamEmitterUnitID integer + * @param startX number + * @param startY number + * @param startZ number + * @param hitX number + * @param hitY number + * @param hitZ number + * + * @return boolean if true the gadget handles the collision event and the engine does not remove the projectile */ bool CSyncedLuaHandle::ShieldPreDamaged( const CProjectile* projectile, @@ -1689,11 +1688,11 @@ bool CSyncedLuaHandle::ShieldPreDamaged( /*** Determines if this weapon can automatically generate targets itself. See also commandFire weaponDef tag. * * @function AllowWeaponTargetCheck - * @number attackerID - * @number attackerWeaponNum - * @number attackerWeaponDefID - * @treturn bool allowCheck - * @treturn bool ignoreCheck + * @param attackerID integer + * @param attackerWeaponNum integer + * @param attackerWeaponDefID integer + * @return boolean allowCheck + * @return boolean ignoreCheck */ int CSyncedLuaHandle::AllowWeaponTargetCheck(unsigned int attackerID, unsigned int attackerWeaponNum, unsigned int attackerWeaponDefID) { @@ -1729,13 +1728,13 @@ int CSyncedLuaHandle::AllowWeaponTargetCheck(unsigned int attackerID, unsigned i /*** Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. * * @function AllowWeaponTarget - * @number attackerID - * @number targetID - * @number attackerWeaponNum - * @number attackerWeaponDefID - * @number defPriority - * @treturn bool allowed - * @treturn number the new priority for this target (if you don't want to change it, return defPriority). Lower priority targets are targeted first. + * @param attackerID integer + * @param targetID integer + * @param attackerWeaponNum integer + * @param attackerWeaponDefID integer + * @param defPriority number + * @return boolean allowed + * @return number the new priority for this target (if you don't want to change it, return defPriority). Lower priority targets are targeted first. */ bool CSyncedLuaHandle::AllowWeaponTarget( unsigned int attackerID, @@ -1795,11 +1794,11 @@ bool CSyncedLuaHandle::AllowWeaponTarget( * * Only called for weaponDefIDs registered via Script.SetWatchWeapon. * - * @number interceptorUnitID - * @number interceptorWeaponID - * @number targetProjectileID + * @param interceptorUnitID integer + * @param interceptorWeaponID integer + * @param targetProjectileID integer * - * @treturn bool allowed + * @return boolean allowed */ bool CSyncedLuaHandle::AllowWeaponInterceptTarget( const CUnit* interceptorUnit, diff --git a/rts/Lua/LuaIntro.cpp b/rts/Lua/LuaIntro.cpp index bda9828d30..318fdbc1bf 100644 --- a/rts/Lua/LuaIntro.cpp +++ b/rts/Lua/LuaIntro.cpp @@ -325,9 +325,10 @@ string CLuaIntro::LoadFile(const string& filename) const /******************************************************************************/ /******************************************************************************/ -/*** Draws custom load screens. +/*** + * Draws custom load screens. * - * @function DrawLoadScreen() + * @function DrawLoadScreen */ void CLuaIntro::DrawLoadScreen() { @@ -352,7 +353,9 @@ void CLuaIntro::DrawLoadScreen() /*** - * @function LoadProgress(message, replaceLastLine) + * @function LoadProgress + * @param message string + * @param replaceLastLine boolean */ void CLuaIntro::LoadProgress(const std::string& msg, const bool replace_lastline) { diff --git a/rts/Lua/LuaMathExtra.cpp b/rts/Lua/LuaMathExtra.cpp index 2295d9d7db..86303d2a7a 100644 --- a/rts/Lua/LuaMathExtra.cpp +++ b/rts/Lua/LuaMathExtra.cpp @@ -12,7 +12,6 @@ static const lua_Number POWERS_OF_TEN[] = {1.0f, 10.0f, 100.0f, 1000.0f, 10000.0 /****************************************************************************** * math extensions - * @module MathExtra * @see rts/Lua/LuaMathExtra.cpp ******************************************************************************/ @@ -35,12 +34,15 @@ bool LuaMathExtra::PushEntries(lua_State* L) /******************************************************************************/ -/*** Returns the length of hypotenuse of right angle triangle with sides x and y, equivalent to sqrt(x*x + y*y), but has better numerical stability and internally handles intermediate overflows/underflows, but is also slower. +/*** + * Returns the length of hypotenuse of right angle triangle with sides x and y, + * equivalent to `sqrt(x*x + y*y)`, but has better numerical stability and + * internally handles intermediate overflows/underflows, but is also slower. * * @function math.hypot - * @number x - * @number y - * @treturn number sqrt(x*x+y*y) + * @param x number + * @param y number + * @return number `sqrt(x*x+y*y)` */ int LuaMathExtra::hypot(lua_State* L) { RECOIL_DETAILED_TRACY_ZONE; @@ -49,14 +51,15 @@ int LuaMathExtra::hypot(lua_State* L) { } -/*** Returns the length of the diagonal of an n-dimensional box (or the length of an n-component vector). Rather quick method that does not handle intermediate overflows/underflows nor is made for numerical stability. +/*** + * Returns the length of the diagonal of an n-dimensional box (or the length of + * an n-component vector). Rather quick method that does not handle intermediate + * overflows/underflows nor is made for numerical stability. * * @function math.diag - * @number x1 - * @number[opt] x2 - * @number[opt] x3 - * @number[opt] xn and so on - * @treturn number diagonal + * @param x number + * @param ... number + * @return number diagonal */ int LuaMathExtra::diag(lua_State* L) { RECOIL_DETAILED_TRACY_ZONE; @@ -73,8 +76,11 @@ int LuaMathExtra::diag(lua_State* L) { /*** Returns x clamped to min and max boundaries. * - * @function math.clamp ( number x, number min, number max ) - * @treturn number clamped + * @function math.clamp + * @param value number + * @param min number + * @param max number + * @return number clamped */ int LuaMathExtra::clamp(lua_State* L) { RECOIL_DETAILED_TRACY_ZONE; @@ -89,8 +95,8 @@ int LuaMathExtra::clamp(lua_State* L) { /*** Returns 0 if x == 0, 1 if x > 0, -1 if x < 0 * * @function math.sgn - * @number x - * @treturn number sign + * @param x number + * @return number sign */ int LuaMathExtra::sgn(lua_State* L) { RECOIL_DETAILED_TRACY_ZONE; @@ -110,10 +116,10 @@ int LuaMathExtra::sgn(lua_State* L) { /*** Returns linear interpolation between x and y with ratio a (x+(y-x)*a). * * @function math.mix - * @number x - * @number y - * @number a - * @treturn number (x+(y-x)*a) + * @param x number + * @param y number + * @param a number + * @return number (x+(y-x)*a) */ int LuaMathExtra::mix(lua_State* L) { RECOIL_DETAILED_TRACY_ZONE; @@ -126,12 +132,15 @@ int LuaMathExtra::mix(lua_State* L) { } -/*** Returns x rounded to n decimals, if n is omitted or <=0, rounds to nearest integer. Note that Spring's Lua interpreter uses 32-bit floats for all numbers so max. precision is ~7 decimal digits. +/*** + * Returns x rounded to n decimals, if n is omitted or <=0, rounds to nearest + * integer. Note that Spring's Lua interpreter uses 32-bit floats for all + * numbers so max. precision is ~7 decimal digits. * * @function math.round - * @number x - * @number decimals - * @treturn number rounded + * @param x number + * @param decimals number + * @return number rounded */ int LuaMathExtra::round(lua_State* L) { RECOIL_DETAILED_TRACY_ZONE; @@ -159,8 +168,8 @@ int LuaMathExtra::round(lua_State* L) { /*** Returns erf(x), the Gauss error function, between -1 and 1. * * @function math.erf - * @number x - * @treturn number erf + * @param x number + * @return number erf */ int LuaMathExtra::erf(lua_State* L) { RECOIL_DETAILED_TRACY_ZONE; @@ -174,10 +183,10 @@ int LuaMathExtra::erf(lua_State* L) { * @function math.smoothstep * Clamps and rescales v to a value between [0; 1] based on the edges and then applies the smoothstep function. * For example math.smoothstep(10, 25, 15) is 0.259, because 15 is 0.333 of the way from 10 to 25, and smoothstep(0.333) is 0.259 - * @number edge0 - * @number edge1 - * @number v - * @treturn number smoothstep + * @param edge0 number + * @param edge1 number + * @param v number + * @return number smoothstep */ int LuaMathExtra::smoothstep(lua_State* L) { RECOIL_DETAILED_TRACY_ZONE; @@ -189,11 +198,9 @@ int LuaMathExtra::smoothstep(lua_State* L) { /*** Returns the normalize vector of an given vector. * * @function math.normalize - * @number x1 - * @number[opt] x2 - * @number[opt] xN and so on - * @treturn number normalized1 - * @treturn number normalized2 and so on + * @param x number + * @param ... number + * @return number ... normalized */ int LuaMathExtra::normalize(lua_State* L) { diff --git a/rts/Lua/LuaMenu.cpp b/rts/Lua/LuaMenu.cpp index 067fa1b2a0..44c4af3959 100644 --- a/rts/Lua/LuaMenu.cpp +++ b/rts/Lua/LuaMenu.cpp @@ -33,7 +33,6 @@ CLuaMenu* luaMenu = nullptr; /****************************************************************************** * Lua Menu API - * @module LuaMenu * @see rts/Lua/LuaMenu.cpp ******************************************************************************/ @@ -372,7 +371,7 @@ bool CLuaMenu::Disable() /*** Called whenever LuaMenu is on with no game loaded. * - * @function ActivateMenu() + * @function ActivateMenu */ void CLuaMenu::ActivateMenu(const std::string& msg) { @@ -393,7 +392,7 @@ void CLuaMenu::ActivateMenu(const std::string& msg) /*** Called whenever LuaMenu is on with a game loaded. * - * @function ActivateGame() + * @function ActivateGame */ void CLuaMenu::ActivateGame() { @@ -413,7 +412,7 @@ void CLuaMenu::ActivateGame() /*** Enables Draw{Genesis,Screen,ScreenPost} callins if true is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running. * - * @function AllowDraw() + * @function AllowDraw * @return boolean allowDraw */ bool CLuaMenu::AllowDraw() diff --git a/rts/Lua/LuaMetalMap.cpp b/rts/Lua/LuaMetalMap.cpp index ce9ec6182f..900d40621f 100644 --- a/rts/Lua/LuaMetalMap.cpp +++ b/rts/Lua/LuaMetalMap.cpp @@ -12,7 +12,6 @@ /****************************************************************************** * Metal Map Lua API - * @module MetalMap * @see rts/Lua/LuaMetalMap.cpp ******************************************************************************/ @@ -52,12 +51,10 @@ int LuaMetalMap::GetMetalAmount(lua_State* L) /*** * @function Spring.SetMetalAmount - * @number x in worldspace/16. - * @number z in worldspace/16. - * @number metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua). - * @treturn nil - * - * + * @param x integer in worldspace/16. + * @param z integer in worldspace/16. + * @param metalAmount number must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua). + * @return nil */ int LuaMetalMap::SetMetalAmount(lua_State* L) { diff --git a/rts/Lua/LuaOpenGL.cpp b/rts/Lua/LuaOpenGL.cpp index b5dd9c979c..e0e4ad7f73 100644 --- a/rts/Lua/LuaOpenGL.cpp +++ b/rts/Lua/LuaOpenGL.cpp @@ -86,7 +86,6 @@ CONFIG(int, DeprecatedGLWarnLevel).defaultValue(0).headlessValue(0).safemodeValu /****************************************************************************** * Lua OpenGL API * - * @module OpenGL * * @see rts/Lua/LuaOpenGL.cpp ******************************************************************************/ @@ -1288,15 +1287,17 @@ int LuaOpenGL::EndText(lua_State* L) return 0; } +/** + * @table gl + */ /*** - * * @function gl.Text - * @string text - * @number x - * @number y - * @number size - * @string[opt] options concatenated string of option characters. + * @param text string + * @param x number + * @param y number + * @param size number + * @param options string? concatenated string of option characters. * * - horizontal alignment: * - 'c' = center @@ -1314,7 +1315,7 @@ int LuaOpenGL::EndText(lua_State* L) * - 's' = shadow * - other: * - 'n' = don't round vertex coords to nearest integer (font may get blurry) - * @treturn nil + * @return nil */ int LuaOpenGL::Text(lua_State* L) { @@ -2527,14 +2528,19 @@ int LuaOpenGL::MemoryBarrier(lua_State* L) ******************************************************************************/ /*** - * * @function gl.Color - * @tparam number|{number,number,number,number} r red when number, rgba - * quadruple or rgb triple otherwise - * @number[opt] g - * @number[opt] b - * @number[opt] a - * @treturn nil + * @param r number Red + * @param g number Green + * @param b number Blue + * @param a number? Alpha (Default: 1.0f) + */ +/*** + * @function gl.Color + * @param rgbs [number,number,number,number] Red, green, blue, alpha + */ +/*** + * @function gl.Color + * @param rgb [number,number,number] Red, green, blue */ int LuaOpenGL::Color(lua_State* L) { diff --git a/rts/Lua/LuaRBOs.cpp b/rts/Lua/LuaRBOs.cpp index f296d2d884..49ac9dfa5d 100644 --- a/rts/Lua/LuaRBOs.cpp +++ b/rts/Lua/LuaRBOs.cpp @@ -13,7 +13,6 @@ /****************************************************************************** * RBO - * @module RBO * @see rts/Lua/LuaRBOs.cpp ******************************************************************************/ @@ -139,23 +138,28 @@ int LuaRBOs::meta_newindex(lua_State* L) /*** * User Data RBO - * @table rbo - * @number target - * @number format - * @number xsize - * @number ysize - * @bool valid - * @number samples will return globalRendering->msaaLevel for multisampled RBO or 0 otherwise + * @class RBO + * @field target GL + * @field format GL + * @field xsize integer + * @field ysize integer + * @field valid boolean + * @field samples integer will return globalRendering->msaaLevel for multisampled RBO or 0 otherwise + */ + +/** + * @class CreateRBOData + * @field target GL + * @field format GL + * @field samples number? any number here will result in creation of multisampled RBO */ /*** * @function gl.CreateRBO - * @number xsize - * @number ysize - * @tparam table data - * @number data.target `GL_RENDERBUFFER_EXT` - * @number data.format `GL_RGBA` - * @number[opt] data.samples any number here will result in creation of multisampled RBO + * @param xsize integer + * @param ysize integer + * @param data CreateRBOData + * @return RBO */ int LuaRBOs::CreateRBO(lua_State* L) { @@ -228,7 +232,7 @@ int LuaRBOs::CreateRBO(lua_State* L) /*** * @function gl.DeleteRBO - * @tparam rbo rbo + * @param rbo RBO */ int LuaRBOs::DeleteRBO(lua_State* L) { diff --git a/rts/Lua/LuaRules.cpp b/rts/Lua/LuaRules.cpp index 0529d8671c..8c5b0e67dc 100644 --- a/rts/Lua/LuaRules.cpp +++ b/rts/Lua/LuaRules.cpp @@ -78,7 +78,6 @@ int CLuaRules::GetInitSelectTeam() const /****************************************************************************** * Lua Rules - * @module LuaRules * * @see rts/Lua/LuaRules.cpp ******************************************************************************/ diff --git a/rts/Lua/LuaShaders.cpp b/rts/Lua/LuaShaders.cpp index b0b17a5d7b..37f64b568d 100644 --- a/rts/Lua/LuaShaders.cpp +++ b/rts/Lua/LuaShaders.cpp @@ -31,7 +31,6 @@ float fltUniformArrayBuf[1024] = {0.0f}; /****************************************************************************** * Shader creation and management - * @module Shaders * * These functions are ONLY available if the graphics adapter supports GLSL. * Please test in your scripts if one of them exists before you use them. In headless mode, the gl. callouts are nil. @@ -199,7 +198,7 @@ bool LuaShaders::DeleteProgram(Program& p) /*** Returns the shader compilation error log. This is empty if the shader linking failed, in that case, check your in/out blocks and ensure they match. * * @function gl.GetShaderLog - * @treturn string infoLog + * @return string infoLog */ int LuaShaders::GetShaderLog(lua_State* L) { @@ -550,38 +549,81 @@ GLint LuaShaders::GetUniformLocation(LuaShaders::Program* p, const char* name) return iter->second.location; } -/*** Create a shader from shaderParams table: - * - * @function gl.CreateShader ( table shaderParams ) - * @tparam table shaderParams - * @treturn number shaderID - * - * ({[ vertex = "glsl code" ,] - * [ tcs = "glsl code" ,] - * [ tes = "glsl code" ,] - * [ geometry = "glsl code" ,] - * [ fragment = "glsl code" ,] - * [ uniform = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays) - * [ uniformInt = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays) - * [ uniformFloat = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays) - * [ uniformMatrix = { uniformName = number value, ...} ,] - * [ geoInputType = number inType,] - * [ geoOutputType = number outType,] - * [ geoOutputVerts = number maxVerts,] - * [ definitions = "string of shader #defines", ] - * }) +/** + * A table of uniform name to value. * - * - The "Vertex" or vertex-shader is your GLSL-Code as string, its written in a C-Dialect. This shader is busy deforming the geometry of a unit but it can not create new polygons. Use it for waves, wobbling surfaces etc. - * - The "Geometry" or Geometry-shader can create new vertices and vertice-stripes from points. - * - The "TCS" or Tesselation Control Shader controls how much tessellation a particular patch gets; it also defines the size of a patch, thus allowing it to augment data. It can also filter vertex data taken from the vertex shader. The main purpose of the TCS is to feed the tessellation levels to the Tessellation primitive generator stage, as well as to feed patch data (as its output values) to the Tessellation Evaluation Shader stage. - * - The "TES" or Tesselation Evaluation Shader takes the abstract patch generated by the tessellation primitive generation stage, as well as the actual vertex data for the entire patch, and generates a particular vertex from it. Each TES invocation generates a single vertex. It can also take per-patch data provided by the Tessellation Control Shader. - * - The "Fragment" or Fragment-shader (sometimes called pixel-Shader) is post processing the allready rendered picture (for example drawing stars on the sky)- remember textures are not always 2 dimensional pictures. They can contain information about the depth, or the third value marks areas and the strength at which these are processed. - * - The Uniforms are the values, you send along with the shader-program. To use them in the shader-program declare them like this: `uniform float frame;` - * - * The engine will automatically fill in an appropriately named uniform for team colour if it is declared; + * The Uniforms are the values you send along with the shader-program. To use + * them in the shader-program declare them like this: `uniform float frame;` + * + * Specify a Lua array to initialize GLSL arrays. + * + * The engine will automatically fill in an appropriately named uniform for team + * colour if it is declared; * - * uniform vec4 teamColor; + * ```glsl + * uniform vec4 teamColor; + * ``` + * + * @class UniformParam : { [string]: T|T[] } + */ + +/*** + * @class ShaderParams + * + * @field vertex string? + * + * The "Vetex" or vertex-shader is your GLSL-Code as string, its written in a + * C-Dialect. This shader is busy deforming the geometry of a unit but it can + * not create new polygons. Use it for waves, wobbling surfaces etc. + * + * @field tcs string? + * + * The "TCS" or Tesselation Control Shader controls how much tessellation a + * particular patch gets; it also defines the size of a patch, thus allowing it + * to augment data. It can also filter vertex data taken from the vertex shader. + * The main purpose of the TCS is to feed the tessellation levels to the + * Tessellation primitive generator stage, as well as to feed patch data (as its + * output values) to the Tessellation Evaluation Shader stage. + * + * @field tes string? + * + * The "TES" or Tesselation Evaluation Shader takes the abstract patch generated + * by the tessellation primitive generation stage, as well as the actual vertex + * data for the entire patch, and generates a particular vertex from it. Each + * TES invocation generates a single vertex. It can also take per-patch data + * provided by the Tessellation Control Shader. + * + * @field geometry string? + * + * The "Geometry" or Geometry-shader can create new vertices and vertice-stripes + * from points. + * + * @field fragment string? + * + * The "Fragment" or Fragment-shader (sometimes called pixel-Shader) is post + * processing the allready rendered picture (for example drawing stars on the + * sky). + * + * Remember textures are not always 2 dimensional pictures. They can contain + * information about the depth, or the third value marks areas and the strength + * at which these are processed. + * + * @field uniform UniformParam? + * @field uniformInt UniformParam? + * @field uniformFloat UniformParam? + * @field uniformMatrix UniformParam? + * @field geoInputType integer? inType + * @field geoOutputType integer? outType + * @field geoOutputVerts integer? maxVerts + * @field definitions string? string of shader #defines" + */ + +/*** + * Create a shader. * + * @function gl.CreateShader + * @param shaderParams ShaderParams + * @return integer shaderID */ int LuaShaders::CreateShader(lua_State* L) { @@ -745,8 +787,7 @@ int LuaShaders::CreateShader(lua_State* L) /*** Deletes a shader identified by shaderID * * @function gl.DeleteShader - * @number shaderID - * @treturn nil + * @param shaderID integer */ int LuaShaders::DeleteShader(lua_State* L) { @@ -763,8 +804,8 @@ int LuaShaders::DeleteShader(lua_State* L) /*** Binds a shader program identified by shaderID. Pass 0 to disable the shader. Returns wether the shader was successfully bound. * * @function gl.UseShader - * @number shaderID - * @treturn bool linked + * @param shaderID integer + * @return boolean linked */ int LuaShaders::UseShader(lua_State* L) { @@ -793,17 +834,16 @@ int LuaShaders::UseShader(lua_State* L) } -/*** Binds a shader program identified by shaderID, and calls the Lua func with the specified arguments. +/*** + * Binds a shader program identified by shaderID, and calls the Lua func with + * the specified arguments. * * Can be used in NON-drawing events (to update uniforms etc.)! * * @function gl.ActiveShader - * @number shaderID - * @func func - * @tparam[opt] any arg1 - * @tparam[opt] any arg2 - * @tparam[opt] any argn - * @treturn nil + * @param shaderID integer + * @param func function + * @param ... any Arguments */ int LuaShaders::ActiveShader(lua_State* L) { @@ -877,12 +917,22 @@ static const char* UniformTypeString(GLenum type) } } +/*** + * @class ActiveUniform + * @field name string + * @field type string String name of `GL_*` constant. + * @field length integer The character length of `name`. + * @field size integer + * @field location GL + */ -/*** Query the active (actually used) uniforms of a shader and identify their names, types (float, int, uint) and sizes (float, vec4, ...). +/*** + * Query the active (actually used) uniforms of a shader and identify their + * names, types (float, int, uint) and sizes (float, vec4, ...). * * @function gl.GetActiveUniforms - * @number shaderID - * @treturn table `ActiveUniforms = { { name = "name", type = "type", length = number length, size = number size }, ...}` + * @param shaderID integer + * @return ActiveUniform[] activeUniforms */ int LuaShaders::GetActiveUniforms(lua_State* L) { @@ -911,12 +961,14 @@ int LuaShaders::GetActiveUniforms(lua_State* L) } -/*** Returns the locationID of a shaders uniform. Needed for changing uniform values with @function gl.Uniform. +/*** + * Returns the locationID of a shaders uniform. Needed for changing uniform + * values with function `gl.Uniform`. * * @function gl.GetUniformLocation - * @number shaderID - * @string name - * @treturn number locationID + * @param shaderID integer + * @param name string + * @return GL locationID */ int LuaShaders::GetUniformLocation(lua_State* L) { @@ -988,15 +1040,16 @@ int LuaShaders::SetFeatureBufferUniforms(lua_State* L) { return SetObjectBufferU /******************************************************************************/ /******************************************************************************/ -/*** Sets the uniform float value at the locationID for the currently active shader. Shader must be activated before setting uniforms. +/*** + * Sets the uniform float value at the locationID for the currently active + * shader. Shader must be activated before setting uniforms. * * @function gl.Uniform - * @number locationID|string uniformName - * @number f1 - * @number[opt] f2 - * @number[opt] f3 - * @number[opt] f4 - * @treturn nil + * @param locationID GL|string uniformName + * @param f1 number + * @param f2 number? + * @param f3 number? + * @param f4 number? */ int LuaShaders::Uniform(lua_State* L) { @@ -1028,15 +1081,16 @@ int LuaShaders::Uniform(lua_State* L) } -/*** Sets the uniform int value at the locationID for the currently active shader. Shader must be activated before setting uniforms. +/*** + * Sets the uniform int value at the locationID for the currently active shader. + * Shader must be activated before setting uniforms. * * @function gl.UniformInt - * @number locationID|string uniformName - * @number int1 - * @number[opt] int2 - * @number[opt] int3 - * @number[opt] int4 - * @treturn nil + * @param locationID integer|string uniformName + * @param int1 integer + * @param int2 integer? + * @param int3 integer? + * @param int4 integer? */ int LuaShaders::UniformInt(lua_State* L) { @@ -1090,14 +1144,23 @@ static bool GLUniformArray(lua_State* L, UniformFunc uf, ParseArrayFunc pf) } #endif +/*** + * @alias UniformArrayType + * | 1 # int + * | 2 # float + * | 3 # float matrix + */ -/*** Sets the an array of uniform values at the locationID for the currently active shader. Shader must be activated before setting uniforms. Type can be one of {1 = int, 2 = float, 3 = float matrix}. +/*** + * Sets the an array of uniform values at the locationID for the currently + * active shader. + * + * Shader must be activated before setting uniforms. * * @function gl.UniformArray - * @number locationID|string uniformName - * @number type - * @tparam table uniforms Array up to 1024 elements - * @treturn nil + * @param locationID integer|string uniformName + * @param type UniformArrayType + * @param uniforms number[] Array up to 1024 elements */ int LuaShaders::UniformArray(lua_State* L) { @@ -1137,15 +1200,30 @@ int LuaShaders::UniformArray(lua_State* L) return 0; } -/*** Sets the a uniform mat4 locationID for the currently active shader. Shader must be activated before setting uniforms. Can set one one common matrix like shadow, or by passing 16 additional numbers for the matrix. +/*** + * Sets the a uniform mat4 locationID for the currently active shader. + * + * Shader must be activated before setting uniforms. + * + * Can set one one common matrix like shadow, or by passing 16 additional + * numbers for the matrix. * * @function gl.UniformMatrix - * @number locationID|string uniformName - * @tparam ?string|number m1 "shadows" | "camera" | "caminv" | "camprj" - * @number[opt] m2 - * @number[opt] mn - * @number[opt] m16 - * @treturn nil + * @param locationID integer|string uniformName + * @param matrix "shadows"|"camera"|"caminv"|"camprj" Name of common matrix. + */ + +/*** + * Sets the a uniform mat4 locationID for the currently active shader. + * + * Shader must be activated before setting uniforms. + * + * Can set one one common matrix like shadow, or by passing 16 additional + * numbers for the matrix. + * + * @function gl.UniformMatrix + * @param locationID number|string uniformName + * @param matrix number[] A 2x2, 3x3 or 4x4 matrix. */ int LuaShaders::UniformMatrix(lua_State* L) { @@ -1229,8 +1307,8 @@ int LuaShaders::UniformSubroutine(lua_State* L) * * Return the GLSL compliant definition of UniformMatricesBuffer(idx=0) or UniformParamsBuffer(idx=1) structure. * - * @number index - * @treturn string glslDefinition + * @param index number + * @return string glslDefinition */ int LuaShaders::GetEngineUniformBufferDef(lua_State* L) { @@ -1251,8 +1329,8 @@ int LuaShaders::GetEngineUniformBufferDef(lua_State* L) * * Return the GLSL compliant definition of ModelUniformData structure (per Unit/Feature buffer available on GPU) * - * @number index - * @treturn string glslDefinition + * @param index number + * @return string glslDefinition */ int LuaShaders::GetEngineModelUniformDataDef(lua_State* L) { @@ -1266,10 +1344,10 @@ int LuaShaders::GetEngineModelUniformDataDef(lua_State* L) /*** Sets the Geometry shader parameters for shaderID. Needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri) * * @function gl.SetGeometryShaderParameter - * @number shaderID - * @number param - * @number number - * @treturn nil + * @param shaderID integer + * @param param number + * @param number number + * @return nil */ int LuaShaders::SetGeometryShaderParameter(lua_State* L) { @@ -1291,14 +1369,16 @@ int LuaShaders::SetGeometryShaderParameter(lua_State* L) return 0; } -/*** Sets the tesselation shader parameters for shaderID. - * - * Needed by tesselation shader programs (check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri) +/*** + * Sets the tesselation shader parameters for `shaderID`. * + * Needed by tesselation shader programs. (Check the opengl + * `GL_ARB_tessellation_shader` extension for `glProgramParameteri`). + * * @function gl.SetTesselationShaderParameter - * @number param - * @number number - * @treturn nil + * @param param integer + * @param value integer + * @return nil */ int LuaShaders::SetTesselationShaderParameter(lua_State* L) { diff --git a/rts/Lua/LuaSyncedCtrl.cpp b/rts/Lua/LuaSyncedCtrl.cpp index 9d6e46dabe..d8eb475e8b 100644 --- a/rts/Lua/LuaSyncedCtrl.cpp +++ b/rts/Lua/LuaSyncedCtrl.cpp @@ -93,7 +93,6 @@ static float smoothMeshAmountChanged = 0.0f; /*** Synced Lua API -@module SyncedCtrl @see rts/Lua/LuaSyncedCtrl.cpp */ @@ -789,10 +788,10 @@ static inline bool IsPlayerSynced(const CPlayer* player) /*** Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID. * * @function Spring.SetAlly - * @number firstAllyTeamID - * @number secondAllyTeamID - * @bool ally - * @treturn nil + * @param firstAllyTeamID integer + * @param secondAllyTeamID integer + * @param ally boolean + * @return nil */ int LuaSyncedCtrl::SetAlly(lua_State* L) { @@ -812,12 +811,12 @@ int LuaSyncedCtrl::SetAlly(lua_State* L) /*** Changes the start box position of an allyTeam. * * @function Spring.SetAllyTeamStartBox - * @number allyTeamID - * @number xMin left start box boundary (elmos) - * @number zMin top start box boundary (elmos) - * @number xMax right start box boundary (elmos) - * @number zMax bottom start box boundary (elmos) - * @treturn nil + * @param allyTeamID integer + * @param xMin number left start box boundary (elmos) + * @param zMin number top start box boundary (elmos) + * @param xMax number right start box boundary (elmos) + * @param zMax number bottom start box boundary (elmos) + * @return nil */ int LuaSyncedCtrl::SetAllyTeamStartBox(lua_State* L) { @@ -844,9 +843,9 @@ int LuaSyncedCtrl::SetAllyTeamStartBox(lua_State* L) /*** Assigns a player to a team. * * @function Spring.AssignPlayerToTeam - * @number playerID - * @number teamID - * @treturn nil + * @param playerID integer + * @param teamID integer + * @return nil */ int LuaSyncedCtrl::AssignPlayerToTeam(lua_State* L) { @@ -872,9 +871,9 @@ int LuaSyncedCtrl::AssignPlayerToTeam(lua_State* L) /*** Changes access to global line of sight for a team and its allies. * * @function Spring.SetGlobalLos - * @number allyTeamID - * @bool globallos - * @treturn nil + * @param allyTeamID integer + * @param globallos boolean + * @return nil */ int LuaSyncedCtrl::SetGlobalLos(lua_State* L) { @@ -899,8 +898,8 @@ int LuaSyncedCtrl::SetGlobalLos(lua_State* L) * * Gaia team cannot be killed. * - * @number teamID - * @treturn nil + * @param teamID integer + * @return nil */ int LuaSyncedCtrl::KillTeam(lua_State* L) { @@ -930,10 +929,10 @@ int LuaSyncedCtrl::KillTeam(lua_State* L) * * A list of winning allyteams can be passed, if undecided (like when dropped from the host) it should be empty (no winner), in the case of a draw with multiple winners, all should be listed. * - * @number[opt] allyTeamID1 - * @number[opt] allyTeamID2 - * @number[opt] allyTeamIDn - * @treturn nil + * @param allyTeamID1 number? + * @param allyTeamID2 number? + * @param allyTeamIDn number? + * @return nil */ int LuaSyncedCtrl::GameOver(lua_State* L) { @@ -974,8 +973,8 @@ int LuaSyncedCtrl::GameOver(lua_State* L) /*** Set tidal strength * * @function Spring.SetTidal - * @number strength - * @treturn nil + * @param strength number + * @return nil */ int LuaSyncedCtrl::SetTidal(lua_State* L) { @@ -987,9 +986,9 @@ int LuaSyncedCtrl::SetTidal(lua_State* L) /*** Set wind strength * * @function Spring.SetWind - * @number minStrength - * @number maxStrength - * @treturn nil + * @param minStrength number + * @param maxStrength number + * @return nil */ int LuaSyncedCtrl::SetWind(lua_State* L) { @@ -1000,10 +999,10 @@ int LuaSyncedCtrl::SetWind(lua_State* L) /*** Adds metal or energy resources to the specified team. * * @function Spring.AddTeamResource - * @number teamID - * @string type "metal" | "energy" - * @number amount - * @treturn nil + * @param teamID integer + * @param type ResourceName + * @param amount number + * @return nil */ int LuaSyncedCtrl::AddTeamResource(lua_State* L) { @@ -1033,14 +1032,24 @@ int LuaSyncedCtrl::AddTeamResource(lua_State* L) return 0; } - -/*** Consumes metal and/or energy resources of the specified team. +/*** + * Consumes metal or energy resources of the specified team. * * @function Spring.UseTeamResource - * @number teamID - * @string type "metal" | "energy" - * @tparam ?number|table amount `{ metal = number amount, energy = number amount }` - * @treturn ?nil|bool hadEnough + * @param teamID integer + * @param type ResourceName Resource type. + * @param amount number Amount of resource to use. + * @return boolean hadEnough + * True if enough of the resource type was available and was consumed, otherwise false. + */ +/*** + * Consumes metal and/or energy resources of the specified team. + * + * @function Spring.UseTeamResource + * @param teamID integer + * @param amount ResourceUsage + * @return boolean hadEnough + * True if enough of the resource type(s) were available and was consumed, otherwise false. */ int LuaSyncedCtrl::UseTeamResource(lua_State* L) { @@ -1121,10 +1130,10 @@ int LuaSyncedCtrl::UseTeamResource(lua_State* L) /*** * @function Spring.SetTeamResource - * @number teamID - * @string res "m" = metal "e" = energy "ms" = metal storage "es" = energy storage - * @number amount - * @treturn nil + * @param teamID integer + * @param resource ResourceName|StorageName + * @param amount number + * @return nil */ int LuaSyncedCtrl::SetTeamResource(lua_State* L) { @@ -1172,10 +1181,10 @@ int LuaSyncedCtrl::SetTeamResource(lua_State* L) /*** Changes the resource amount for a team beyond which resources aren't stored but transferred to other allied teams if possible. * * @function Spring.SetTeamShareLevel - * @number teamID - * @string type "metal" | "energy" - * @number amount - * @treturn nil + * @param teamID integer + * @param type ResourceName + * @param amount number + * @return nil */ int LuaSyncedCtrl::SetTeamShareLevel(lua_State* L) { @@ -1209,11 +1218,11 @@ int LuaSyncedCtrl::SetTeamShareLevel(lua_State* L) /*** Transfers resources between two teams. * * @function Spring.ShareTeamResource - * @number teamID_src - * @number teamID_recv - * @string type "metal" | "energy" - * @number amount - * @treturn nil + * @param teamID_src integer + * @param teamID_recv integer + * @param type ResourceName + * @param amount number + * @return nil */ int LuaSyncedCtrl::ShareTeamResource(lua_State* L) { @@ -1281,21 +1290,32 @@ int LuaSyncedCtrl::ShareTeamResource(lua_State* L) * @section rulesparams ******************************************************************************/ -/*** Parameters for los access +/*** + * Parameters for los access + * + * + * If one condition is fulfilled all beneath it are too (e.g. if an unit is in + * LOS it can read params with `inradar=true` even if the param has + * `inlos=false`) All GameRulesParam are public, TeamRulesParams can just be + * `private`,`allied` and/or `public` You can read RulesParams from any Lua + * enviroments! With those losAccess policies you can limit their access. * - * @table losAccess - * If one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it can read params with `inradar=true` even if the param has `inlos=false`) * All GameRulesParam are public, TeamRulesParams can just be `private`,`allied` and/or `public` * You can read RulesParams from any Lua enviroments! With those losAccess policies you can limit their access. * - * @bool[opt] private only readable by the ally (default) - * @bool[opt] allied readable by ally + ingame allied - * @bool[opt] inlos readable if the unit is in LOS - * @bool[opt] inradar readable if the unit is in AirLOS - * @bool[opt] public readable by all + * @class losAccess + * + * @field public private boolean? only readable by the ally (default) + * @field public allied boolean? readable by ally + ingame allied + * @field public inlos boolean? readable if the unit is in LOS + * @field public inradar boolean? readable if the unit is in AirLOS + * @field public public boolean? readable by all + */ +/* NOTE: Need to explicitly declare `public` scope here to prevent LLS from + * detecting field names `public`/`private` as an access modifier. + * + * See https://github.com/LuaLS/lua-language-server/issues/1814 */ - - void SetRulesParam(lua_State* L, const char* caller, int offset, LuaRulesParams::Params& params) { @@ -1355,10 +1375,10 @@ void SetRulesParam(lua_State* L, const char* caller, int offset, /*** * @function Spring.SetGameRulesParam - * @string paramName - * @tparam ?number|string paramValue numeric paramValues in quotes will be converted to number. - * @tparam[opt] losAccess losAccess - * @treturn nil + * @param paramName string + * @param paramValue ?number|string numeric paramValues in quotes will be converted to number. + * @param losAccess losAccess? + * @return nil */ int LuaSyncedCtrl::SetGameRulesParam(lua_State* L) { @@ -1369,11 +1389,11 @@ int LuaSyncedCtrl::SetGameRulesParam(lua_State* L) /*** * @function Spring.SetTeamRulesParam - * @number teamID - * @string paramName - * @tparam ?number|string paramValue numeric paramValues in quotes will be converted to number. - * @tparam[opt] losAccess losAccess - * @treturn nil + * @param teamID integer + * @param paramName string + * @param paramValue ?number|string numeric paramValues in quotes will be converted to number. + * @param losAccess losAccess? + * @return nil */ int LuaSyncedCtrl::SetTeamRulesParam(lua_State* L) { @@ -1387,11 +1407,11 @@ int LuaSyncedCtrl::SetTeamRulesParam(lua_State* L) /*** * @function Spring.SetPlayerRulesParam - * @number playerID - * @string paramName - * @tparam ?number|string paramValue numeric paramValues in quotes will be converted to number. - * @tparam[opt] losAccess losAccess - * @treturn nil + * @param playerID integer + * @param paramName string + * @param paramValue ?number|string numeric paramValues in quotes will be converted to number. + * @param losAccess losAccess? + * @return nil */ int LuaSyncedCtrl::SetPlayerRulesParam(lua_State* L) { @@ -1411,11 +1431,11 @@ int LuaSyncedCtrl::SetPlayerRulesParam(lua_State* L) /*** * * @function Spring.SetUnitRulesParam - * @number unitID - * @string paramName - * @tparam ?number|string paramValue numeric paramValues in quotes will be converted to number. - * @tparam[opt] losAccess losAccess - * @treturn nil + * @param unitID integer + * @param paramName string + * @param paramValue ?number|string numeric paramValues in quotes will be converted to number. + * @param losAccess losAccess? + * @return nil */ int LuaSyncedCtrl::SetUnitRulesParam(lua_State* L) { @@ -1431,11 +1451,11 @@ int LuaSyncedCtrl::SetUnitRulesParam(lua_State* L) /*** * @function Spring.SetFeatureRulesParam - * @number featureID - * @string paramName - * @tparam ?number|string paramValue numeric paramValues in quotes will be converted to number. - * @tparam[opt] losAccess losAccess - * @treturn nil + * @param featureID integer + * @param paramName string + * @param paramValue ?number|string numeric paramValues in quotes will be converted to number. + * @param losAccess losAccess? + * @return nil */ int LuaSyncedCtrl::SetFeatureRulesParam(lua_State* L) { @@ -1495,16 +1515,11 @@ static inline void ParseCobArgs( /*** * @function Spring.CallCOBScript - * @number unitID - * @tparam ?number|string funcName - * @number retArgs - * @param[opt] COBArg1 - * @param[opt] COBArg2 - * @param[opt] COBArgn - * @treturn ?nil|number returnValue - * @treturn ?nil|number returnArg1 - * @treturn ?nil|number returnArg2 - * @treturn ?nil|number returnArgn + * @param unitID integer + * @param funcName integer|string? Function ID or name. + * @param retArgs integer Number of values to return. + * @param ... any Arguments + * @return number ... */ int LuaSyncedCtrl::CallCOBScript(lua_State* L) { @@ -1561,9 +1576,9 @@ int LuaSyncedCtrl::CallCOBScript(lua_State* L) /*** * @function Spring.GetCOBScriptID - * @number unitID - * @string funcName - * @treturn ?nil|number funcID + * @param unitID integer + * @param funcName string + * @return integer? funcID */ int LuaSyncedCtrl::GetCOBScriptID(lua_State* L) { @@ -1604,17 +1619,17 @@ int LuaSyncedCtrl::GetCOBScriptID(lua_State* L) * * Offmap positions are clamped! Use MoveCtrl to move to such positions. * - * @tparam string|number unitDefName or unitDefID - * @number x - * @number y - * @number z - * @tparam string|number facing possible values for facing are: "south" | "s" | 0, "east" | "e" | 1, "north" | "n" | 2, "west" | "w" | 3 - * @number teamID - * @bool[opt=false] build the unit is created in "being built" state with buildProgress = 0 - * @bool[opt=true] flattenGround the unit flattens ground, if it normally does so - * @number[opt] unitID requests specific unitID - * @number[opt] builderID - * @treturn number|nil unitID meaning unit was created + * @param unitDefName string|number or unitDefID + * @param x number + * @param y number + * @param z number + * @param facing Facing + * @param teamID integer + * @param build boolean? (Default: false) the unit is created in "being built" state with buildProgress = 0 + * @param flattenGround boolean? (Default: true) the unit flattens ground, if it normally does so + * @param unitID integer? requests specific unitID + * @param builderID integer? + * @return number|nil unitID meaning unit was created */ int LuaSyncedCtrl::CreateUnit(lua_State* L) { @@ -1703,12 +1718,12 @@ int LuaSyncedCtrl::CreateUnit(lua_State* L) /*** * @function Spring.DestroyUnit * @see Spring.CreateUnit - * @number unitID - * @bool[opt=false] selfd makes the unit act like it self-destructed. - * @bool[opt=false] reclaimed don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team! - * @number[opt] attackerID - * @bool[opt=false] cleanupImmediately stronger version of reclaimed, removes the unit unconditionally and makes its ID available for immediate reuse (otherwise it takes a few frames) - * @treturn nil + * @param unitID integer + * @param selfd boolean? (Default: false) makes the unit act like it self-destructed. + * @param reclaimed boolean? (Default: false) don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team! + * @param attackerID integer? + * @param cleanupImmediately boolean? (Default: false) stronger version of reclaimed, removes the unit unconditionally and makes its ID available for immediate reuse (otherwise it takes a few frames) + * @return nil */ int LuaSyncedCtrl::DestroyUnit(lua_State* L) { @@ -1747,10 +1762,10 @@ int LuaSyncedCtrl::DestroyUnit(lua_State* L) /*** * @function Spring.TransferUnit - * @number unitID - * @number newTeamID - * @bool[opt=true] given if false, the unit is captured. - * @treturn nil + * @param unitID integer + * @param newTeamID integer + * @param given boolean? (Default: true) if false, the unit is captured. + * @return nil */ int LuaSyncedCtrl::TransferUnit(lua_State* L) { @@ -1792,9 +1807,9 @@ int LuaSyncedCtrl::TransferUnit(lua_State* L) /*** * @function Spring.SetUnitCosts - * @number unitID - * @tparam {[number]=number,...} where keys and values are, respectively and in this order: buildTime=amount, metalCost=amount, energyCost=amount - * @treturn nil + * @param unitID integer + * @param where table keys and values are, respectively and in this order: buildTime=amount, metalCost=amount, energyCost=amount + * @return nil */ int LuaSyncedCtrl::SetUnitCosts(lua_State* L) { @@ -1921,17 +1936,17 @@ static bool SetUnitStorageParam(CUnit* unit, const char* name, float value) /*** * @function Spring.SetUnitResourcing - * @number unitID - * @string res - * @number amount - * @treturn nil + * @param unitID integer + * @param res string + * @param amount number + * @return nil */ /*** * @function Spring.SetUnitResourcing - * @number unitID - * @tparam {[string]=number,...} res keys are: "[u|c][u|m][m|e]" unconditional | conditional, use | make, metal | energy. Values are amounts - * @treturn nil + * @param unitID integer + * @param res table keys are: "[u|c][u|m][m|e]" unconditional | conditional, use | make, metal | energy. Values are amounts + * @return nil */ int LuaSyncedCtrl::SetUnitResourcing(lua_State* L) { @@ -1967,17 +1982,15 @@ int LuaSyncedCtrl::SetUnitResourcing(lua_State* L) /*** * @function Spring.SetUnitStorage - * @number unitID - * @string res - * @number amount - * @treturn nil + * @param unitID number + * @param res string + * @param amount number */ /*** * @function Spring.SetUnitStorage - * @number unitID - * @tparam {[string]=number,...} res keys are: "[m|e]" metal | energy. Values are amounts - * @treturn nil + * @param unitID number + * @param res ResourceUsage keys are: "[m|e]" metal | energy. Values are amounts */ int LuaSyncedCtrl::SetUnitStorage(lua_State* L) { @@ -2008,9 +2021,9 @@ int LuaSyncedCtrl::SetUnitStorage(lua_State* L) /*** * @function Spring.SetUnitTooltip - * @number unitID - * @string tooltip - * @treturn nil + * @param unitID integer + * @param tooltip string + * @return nil */ int LuaSyncedCtrl::SetUnitTooltip(lua_State* L) { @@ -2032,9 +2045,9 @@ int LuaSyncedCtrl::SetUnitTooltip(lua_State* L) /*** * @function Spring.SetUnitHealth - * @number unitID - * @tparam number|{[string]=number,...} health where keys can be one of health|capture|paralyze|build and values are amounts - * @treturn nil + * @param unitID integer + * @param health number|table where keys can be one of health|capture|paralyze|build and values are amounts + * @return nil */ int LuaSyncedCtrl::SetUnitHealth(lua_State* L) { @@ -2087,9 +2100,9 @@ int LuaSyncedCtrl::SetUnitHealth(lua_State* L) /*** * @function Spring.SetUnitMaxHealth - * @number unitID - * @number maxHealth - * @treturn nil + * @param unitID integer + * @param maxHealth number + * @return nil */ int LuaSyncedCtrl::SetUnitMaxHealth(lua_State* L) { @@ -2106,10 +2119,10 @@ int LuaSyncedCtrl::SetUnitMaxHealth(lua_State* L) /*** * @function Spring.SetUnitStockpile - * @number unitID - * @number[opt] stockpile - * @number[opt] buildPercent - * @treturn nil + * @param unitID integer + * @param stockpile number? + * @param buildPercent number? + * @return nil */ int LuaSyncedCtrl::SetUnitStockpile(lua_State* L) { @@ -2135,6 +2148,30 @@ int LuaSyncedCtrl::SetUnitStockpile(lua_State* L) } +/*** Parameter for weapon states + * + * @class WeaponState + * @field reloadState integer? + * @field reloadFrame integer? Alias for `reloadState`. + * @field reloadTime number? + * @field reaimTime integer? + * @field accuracy number? + * @field sprayAngle number? + * @field range number? + * If you change the range of a weapon with dynamic damage make sure you use `SetUnitWeaponDamages` to change dynDamageRange as well. + * @field projectileSpeed number? + * @field burst integer? + * @field burstRate number? + * @field projectiles integer? + * @field salvoLeft integer? + * @field nextSalvo integer? + * @field aimReady number? + * Set to `true` if a non-zero value is passed, `false` is zero is passed. + * @field forceAim integer? + * @field avoidFlags integer? + * @field collisionFlags integer? + */ + static bool SetSingleUnitWeaponState(lua_State* L, CWeapon* weapon, int index) { // FIXME: missing checks and updates? @@ -2218,10 +2255,10 @@ static bool SetSingleUnitWeaponState(lua_State* L, CWeapon* weapon, int index) /*** * * @function Spring.SetUnitUseWeapons - * @number unitID - * @number[opt] forceUseWeapons - * @number[opt] allowUseWeapons - * @treturn nil + * @param unitID integer + * @param forceUseWeapons number? + * @param allowUseWeapons number? + * @return nil */ int LuaSyncedCtrl::SetUnitUseWeapons(lua_State* L) { @@ -2235,39 +2272,21 @@ int LuaSyncedCtrl::SetUnitUseWeapons(lua_State* L) return 0; } -/*** Parameter for weapon states - * - * @table states - * @number reloadState - * @number reloadFrame synonym for reloadState! - * @number reloadTime - * @number accuracy - * @number sprayAngle - * @number range if you change the range of a weapon with dynamic damage make sure you use `SetUnitWeaponDamages` to change dynDamageRange as well. - * @number projectileSpeed - * @number burst - * @number burstRate - * @number projectiles - * @number salvoLeft - * @number nextSalvo - * @number aimReady (<>0.0f := true) - */ - /*** * @function Spring.SetUnitWeaponState - * @number unitID - * @number weaponNum - * @tparam states states - * @treturn nil + * @param unitID integer + * @param weaponNum number + * @param states WeaponState + * @return nil */ /*** * @function Spring.SetUnitWeaponState - * @number unitID - * @number weaponNum - * @string key - * @number value - * @treturn nil + * @param unitID integer + * @param weaponNum number + * @param key string + * @param value number + * @return nil */ int LuaSyncedCtrl::SetUnitWeaponState(lua_State* L) { @@ -2300,6 +2319,24 @@ int LuaSyncedCtrl::SetUnitWeaponState(lua_State* L) return 0; } +/*** Parameters for damage + * + * @class WeaponDamages + * @field paralyzeDamageTime integer + * @field impulseFactor number + * @field impulseBoost number + * @field craterMult number + * @field craterBoost number + * @field dynDamageExp number + * @field dynDamageMin number + * @field dynDamageRange number + * @field dynDamageInverted number + * Set to `true` if a non-zero value is passed, `false` is zero is passed. + * @field craterAreaOfEffect number + * @field damageAreaOfEffect number + * @field edgeEffectiveness number + * @field explosionSpeed number + */ static int SetSingleDynDamagesKey(lua_State* L, DynDamageArray* damages, int index) { @@ -2370,39 +2407,20 @@ static int SetSingleDynDamagesKey(lua_State* L, DynDamageArray* damages, int ind } -/*** Parameters for damage - * - * @table damages - * @number paralyzeDamageTime - * @number impulseFactor - * @number impulseBoost - * @number craterMult - * @number craterBoost - * @number dynDamageExp - * @number dynDamageMin - * @number dynDamageRange - * @number dynDamageInverted (<>0.0f := true) - * @number craterAreaOfEffect - * @number damageAreaOfEffect - * @number edgeEffectiveness - * @number explosionSpeed - * @number armorType - */ - /*** * @function Spring.SetUnitWeaponDamages - * @number unitID - * @tparam ?number|string weaponNum "selfDestruct" | "explode" - * @tparam damages damages - * @treturn nil + * @param unitID integer + * @param weaponNum number|"selfDestruct"|"explode" + * @param damages WeaponDamages + * @return nil */ /*** * @function Spring.SetUnitWeaponDamages - * @number unitID - * @tparam ?number|string weaponNum "selfDestruct" | "explode" - * @string key - * @number value - * @treturn nil + * @param unitID integer + * @param weaponNum number|"selfDestruct"|"explode" + * @param key string + * @param value number + * @return nil */ int LuaSyncedCtrl::SetUnitWeaponDamages(lua_State* L) { @@ -2451,9 +2469,9 @@ int LuaSyncedCtrl::SetUnitWeaponDamages(lua_State* L) /*** @function Spring.SetUnitMaxRange * - * @number unitID - * @number maxRange - * @treturn nil + * @param unitID integer + * @param maxRange number + * @return nil */ int LuaSyncedCtrl::SetUnitMaxRange(lua_State* L) { @@ -2471,9 +2489,9 @@ int LuaSyncedCtrl::SetUnitMaxRange(lua_State* L) * @function Spring.SetUnitExperience * @see Spring.AddUnitExperience * @see Spring.GetUnitExperience - * @number unitID - * @number experience - * @treturn nil + * @param unitID integer + * @param experience number + * @return nil */ int LuaSyncedCtrl::SetUnitExperience(lua_State* L) { @@ -2490,9 +2508,9 @@ int LuaSyncedCtrl::SetUnitExperience(lua_State* L) * @function Spring.AddUnitExperience * @see Spring.SetUnitExperience * @see Spring.GetUnitExperience - * @number unitID - * @number deltaExperience Can be negative to subtract, but the unit will never have negative total afterwards - * @treturn nil + * @param unitID integer + * @param deltaExperience number Can be negative to subtract, but the unit will never have negative total afterwards + * @return nil */ int LuaSyncedCtrl::AddUnitExperience(lua_State* L) { @@ -2509,10 +2527,10 @@ int LuaSyncedCtrl::AddUnitExperience(lua_State* L) /*** * @function Spring.SetUnitArmored - * @number unitID - * @bool[opt] armored - * @number[opt] armorMultiple - * @treturn nil + * @param unitID integer + * @param armored boolean? + * @param armorMultiple number? + * @return nil */ int LuaSyncedCtrl::SetUnitArmored(lua_State* L) { @@ -2600,10 +2618,10 @@ static unsigned char ParseLosBits(lua_State* L, int index, unsigned char bits) * [contRadar = boolean] * } * - * @number unitID - * @number allyTeam - * @tparam number|table losTypes - * @treturn nil + * @param unitID integer + * @param allyTeam number + * @param losTypes number|table + * @return nil */ int LuaSyncedCtrl::SetUnitLosMask(lua_State* L) { @@ -2631,10 +2649,10 @@ int LuaSyncedCtrl::SetUnitLosMask(lua_State* L) /*** * @function Spring.SetUnitLosState - * @number unitID - * @number allyTeam - * @tparam number|table los - * @treturn nil + * @param unitID integer + * @param allyTeam number + * @param los number|table + * @return nil */ int LuaSyncedCtrl::SetUnitLosState(lua_State* L) { @@ -2671,10 +2689,10 @@ int LuaSyncedCtrl::SetUnitLosState(lua_State* L) * - if the boolean is false it takes the default decloak distance for that unitdef, * - if the boolean is true it takes the absolute value of it. * - * @number unitID - * @tparam bool|number cloak - * @tparam bool|number cloakArg - * @treturn nil + * @param unitID integer + * @param cloak boolean|number + * @param cloakArg boolean|number + * @return nil */ int LuaSyncedCtrl::SetUnitCloak(lua_State* L) { @@ -2708,9 +2726,9 @@ int LuaSyncedCtrl::SetUnitCloak(lua_State* L) /*** * @function Spring.SetUnitStealth - * @number unitID - * @bool stealth - * @treturn nil + * @param unitID integer + * @param stealth boolean + * @return nil */ int LuaSyncedCtrl::SetUnitStealth(lua_State* L) { @@ -2726,9 +2744,9 @@ int LuaSyncedCtrl::SetUnitStealth(lua_State* L) /*** * @function Spring.SetUnitSonarStealth - * @number unitID - * @bool sonarStealth - * @treturn nil + * @param unitID integer + * @param sonarStealth boolean + * @return nil */ int LuaSyncedCtrl::SetUnitSonarStealth(lua_State* L) { @@ -2743,9 +2761,9 @@ int LuaSyncedCtrl::SetUnitSonarStealth(lua_State* L) /*** * @function Spring.SetUnitSeismicSignature - * @number unitID - * @number seismicSignature - * @treturn nil + * @param unitID integer + * @param seismicSignature number + * @return nil */ int LuaSyncedCtrl::SetUnitSeismicSignature(lua_State* L) { @@ -2759,9 +2777,9 @@ int LuaSyncedCtrl::SetUnitSeismicSignature(lua_State* L) /*** * @function Spring.SetUnitAlwaysVisible - * @number unitID - * @bool alwaysVisible - * @treturn nil + * @param unitID integer + * @param alwaysVisible boolean + * @return nil */ int LuaSyncedCtrl::SetUnitAlwaysVisible(lua_State* L) { @@ -2772,9 +2790,9 @@ int LuaSyncedCtrl::SetUnitAlwaysVisible(lua_State* L) /*** * * @function Spring.SetUnitUseAirLos - * @number unitID - * @bool useAirLos - * @treturn nil + * @param unitID integer + * @param useAirLos boolean + * @return nil */ int LuaSyncedCtrl::SetUnitUseAirLos(lua_State* L) { @@ -2784,10 +2802,10 @@ int LuaSyncedCtrl::SetUnitUseAirLos(lua_State* L) /*** * @function Spring.SetUnitMetalExtraction - * @number unitID - * @number depth corresponds to metal extraction rate - * @number[opt] range similar to "extractsMetal" in unitDefs. - * @treturn nil + * @param unitID integer + * @param depth number corresponds to metal extraction rate + * @param range number? similar to "extractsMetal" in unitDefs. + * @return nil */ int LuaSyncedCtrl::SetUnitMetalExtraction(lua_State* L) { @@ -2812,9 +2830,9 @@ int LuaSyncedCtrl::SetUnitMetalExtraction(lua_State* L) /*** See also harvestStorage UnitDef tag. * * @function Spring.SetUnitHarvestStorage - * @number unitID - * @number metal - * @treturn nil + * @param unitID integer + * @param metal number + * @return nil */ int LuaSyncedCtrl::SetUnitHarvestStorage(lua_State* L) { @@ -2833,10 +2851,10 @@ int LuaSyncedCtrl::SetUnitHarvestStorage(lua_State* L) /*** * * @function Spring.SetUnitBuildParams - * @number unitID - * @string paramName one of `buildRange`|`buildDistance`|`buildRange3D` - * @number|bool value bool when `paramName` is `buildRange3D`, number otherwise - * @treturn nil + * @param unitID integer + * @param paramName string one of `buildRange`|`buildDistance`|`buildRange3D` + * @param value number|boolean boolean when `paramName` is `buildRange3D`, otherwise number. + * @return nil */ int LuaSyncedCtrl::SetUnitBuildParams(lua_State* L) { @@ -2866,13 +2884,13 @@ int LuaSyncedCtrl::SetUnitBuildParams(lua_State* L) /*** * @function Spring.SetUnitBuildSpeed - * @number builderID - * @number buildSpeed - * @number[opt] repairSpeed - * @number[opt] reclaimSpeed - * @number[opt] captureSpeed - * @number[opt] terraformSpeed - * @treturn nil + * @param builderID integer + * @param buildSpeed number + * @param repairSpeed number? + * @param reclaimSpeed number? + * @param captureSpeed number? + * @param terraformSpeed number? + * @return nil */ int LuaSyncedCtrl::SetUnitBuildSpeed(lua_State* L) { @@ -2921,9 +2939,9 @@ int LuaSyncedCtrl::SetUnitBuildSpeed(lua_State* L) * This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end * Use it! * - * @number builderID - * @tparam table pieces - * @treturn nil + * @param builderID integer + * @param pieces table + * @return nil * */ int LuaSyncedCtrl::SetUnitNanoPieces(lua_State* L) @@ -2977,15 +2995,15 @@ int LuaSyncedCtrl::SetUnitNanoPieces(lua_State* L) /*** * @function Spring.SetUnitBlocking - * @number unitID - * @bool isblocking - * @bool isSolidObjectCollidable - * @bool isProjectileCollidable - * @bool isRaySegmentCollidable - * @bool crushable - * @bool blockEnemyPushing - * @bool blockHeightChanges - * @treturn nil + * @param unitID integer + * @param isblocking boolean + * @param isSolidObjectCollidable boolean + * @param isProjectileCollidable boolean + * @param isRaySegmentCollidable boolean + * @param crushable boolean + * @param blockEnemyPushing boolean + * @param blockHeightChanges boolean + * @return nil */ int LuaSyncedCtrl::SetUnitBlocking(lua_State* L) { @@ -2995,9 +3013,9 @@ int LuaSyncedCtrl::SetUnitBlocking(lua_State* L) /*** * @function Spring.SetUnitCrashing - * @number unitID - * @bool crashing - * @treturn bool success + * @param unitID integer + * @param crashing boolean + * @return boolean success */ int LuaSyncedCtrl::SetUnitCrashing(lua_State* L) { CUnit* unit = ParseUnit(L, __func__, 1); @@ -3030,11 +3048,11 @@ int LuaSyncedCtrl::SetUnitCrashing(lua_State* L) { /*** * @function Spring.SetUnitShieldState - * @number unitID - * @number[opt=-1] weaponID - * @bool[opt] enabled - * @number[opt] power - * @treturn nil + * @param unitID integer + * @param weaponID integer? (Default: -1) + * @param enabled boolean? + * @param power number? + * @return nil */ int LuaSyncedCtrl::SetUnitShieldState(lua_State* L) { @@ -3068,10 +3086,10 @@ int LuaSyncedCtrl::SetUnitShieldState(lua_State* L) /*** * @function Spring.SetUnitShieldRechargeDelay - * @number unitID - * @number[opt] weaponID (optional if the unit only has one shield) - * @number[opt] rechargeTime (in seconds; emulates a regular hit if nil) - * @treturn nil + * @param unitID integer + * @param weaponID integer? (optional if the unit only has one shield) + * @param rechargeTime number? (in seconds; emulates a regular hit if nil) + * @return nil */ int LuaSyncedCtrl::SetUnitShieldRechargeDelay(lua_State* L) { @@ -3105,12 +3123,12 @@ int LuaSyncedCtrl::SetUnitShieldRechargeDelay(lua_State* L) /*** * @function Spring.SetUnitFlanking - * @number unitID - * @string type "dir"|"minDamage"|"maxDamage"|"moveFactor"|"mode" - * @number arg1 x|minDamage|maxDamage|moveFactor|mode - * @number[opt] y only when type is "dir" - * @number[opt] z only when type is "dir" - * @treturn nil + * @param unitID integer + * @param type string "dir"|"minDamage"|"maxDamage"|"moveFactor"|"mode" + * @param arg1 number x|minDamage|maxDamage|moveFactor|mode + * @param y number? only when type is "dir" + * @param z number? only when type is "dir" + * @return nil */ int LuaSyncedCtrl::SetUnitFlanking(lua_State* L) { @@ -3152,9 +3170,9 @@ int LuaSyncedCtrl::SetUnitFlanking(lua_State* L) /*** * @function Spring.SetUnitPhysicalStateBit - * @number unitID - * @number[bit] Physical state bit - * @treturn nil + * @param unitID integer + * @param Physical number[bit] state bit + * @return nil */ int LuaSyncedCtrl::SetUnitPhysicalStateBit(lua_State* L) { @@ -3171,8 +3189,8 @@ int LuaSyncedCtrl::SetUnitPhysicalStateBit(lua_State* L) /*** * @function Spring.GetUnitPhysicalState - * @number unitID - * @treturn number Unit's PhysicalState bitmask + * @param unitID integer + * @return number Unit's PhysicalState bitmask */ int LuaSyncedCtrl::GetUnitPhysicalState(lua_State* L) { @@ -3196,9 +3214,9 @@ int LuaSyncedCtrl::SetUnitFuel(lua_State* L) { return 0; } // FIXME: DELETE ME * * @function Spring.SetUnitNeutral * - * @number unitID - * @bool neutral - * @treturn nil|bool setNeutral + * @param unitID integer + * @param neutral boolean + * @return nil|boolean setNeutral */ int LuaSyncedCtrl::SetUnitNeutral(lua_State* L) { @@ -3215,24 +3233,24 @@ int LuaSyncedCtrl::SetUnitNeutral(lua_State* L) /*** Defines a unit's target. * * @function Spring.SetUnitTarget - * @number unitID - * @number[opt] enemyUnitID when nil drops the units current target. - * @bool[opt=false] dgun - * @bool[opt=false] userTarget - * @number[opt=-1] weaponNum - * @treturn bool success + * @param unitID integer + * @param enemyUnitID integer? when nil drops the units current target. + * @param dgun boolean? (Default: false) + * @param userTarget boolean? (Default: false) + * @param weaponNum number? (Default: -1) + * @return boolean success */ /*** * @function Spring.SetUnitTarget - * @number unitID - * @number[opt] x when nil or not passed it will drop target and ignore other parameters - * @number[opt] y - * @number[opt] z - * @bool[opt=false] dgun - * @bool[opt=false] userTarget - * @number[opt=-1] weaponNum - * @treturn bool success + * @param unitID integer + * @param x number? when nil or not passed it will drop target and ignore other parameters + * @param y number? + * @param z number? + * @param dgun boolean? (Default: false) + * @param userTarget boolean? (Default: false) + * @param weaponNum number? (Default: -1) + * @return boolean success */ int LuaSyncedCtrl::SetUnitTarget(lua_State* L) { @@ -3294,15 +3312,15 @@ int LuaSyncedCtrl::SetUnitTarget(lua_State* L) /*** * @function Spring.SetUnitMidAndAimPos - * @number unitID - * @number mpX new middle positionX of unit - * @number mpY new middle positionY of unit - * @number mpZ new middle positionZ of unit - * @number apX new positionX that enemies aim at on this unit - * @number apY new positionY that enemies aim at on this unit - * @number apZ new positionZ that enemies aim at on this unit - * @bool[opt=false] relative are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted! - * @treturn bool success + * @param unitID integer + * @param mpX number new middle positionX of unit + * @param mpY number new middle positionY of unit + * @param mpZ number new middle positionZ of unit + * @param apX number new positionX that enemies aim at on this unit + * @param apY number new positionY that enemies aim at on this unit + * @param apZ number new positionZ that enemies aim at on this unit + * @param relative boolean? (Default: false) are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted! + * @return boolean success */ int LuaSyncedCtrl::SetUnitMidAndAimPos(lua_State* L) { @@ -3342,10 +3360,10 @@ int LuaSyncedCtrl::SetUnitMidAndAimPos(lua_State* L) /*** * @function Spring.SetUnitRadiusAndHeight - * @number unitID - * @number radius - * @number height - * @treturn bool success + * @param unitID integer + * @param radius number + * @param height number + * @return boolean success */ int LuaSyncedCtrl::SetUnitRadiusAndHeight(lua_State* L) { @@ -3379,9 +3397,9 @@ int LuaSyncedCtrl::SetUnitRadiusAndHeight(lua_State* L) /*** * @function Spring.SetUnitBuildeeRadius * Sets the unit's radius for when targeted by build, repair, reclaim-type commands. - * @number unitID - * @number build radius for when targeted by build, repair, reclaim-type commands. - * @treturn nil + * @param unitID integer + * @param build number radius for when targeted by build, repair, reclaim-type commands. + * @return nil */ int LuaSyncedCtrl::SetUnitBuildeeRadius(lua_State* L) { @@ -3399,10 +3417,10 @@ int LuaSyncedCtrl::SetUnitBuildeeRadius(lua_State* L) /*** Changes the pieces hierarchy of a unit by attaching a piece to a new parent. * * @function Spring.SetUnitPieceParent - * @number unitID - * @number AlteredPiece - * @number ParentPiece - * @treturn nil + * @param unitID integer + * @param AlteredPiece number + * @param ParentPiece number + * @return nil */ int LuaSyncedCtrl::SetUnitPieceParent(lua_State* L) { @@ -3443,10 +3461,10 @@ int LuaSyncedCtrl::SetUnitPieceParent(lua_State* L) * * If any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed. * - * @number unitID - * @number pieceNum - * @tparam {number,...} matrix an array of 16 floats - * @treturn nil + * @param unitID integer + * @param pieceNum number + * @param matrix number[] an array of 16 floats + * @return nil */ int LuaSyncedCtrl::SetUnitPieceMatrix(lua_State* L) { @@ -3475,17 +3493,17 @@ int LuaSyncedCtrl::SetUnitPieceMatrix(lua_State* L) /*** * @function Spring.SetUnitCollisionVolumeData - * @number unitID - * @number scaleX - * @number scaleY - * @number scaleZ - * @number offsetX - * @number offsetY - * @number offsetZ - * @number vType - * @number tType - * @number Axis - * @treturn nil + * @param unitID integer + * @param scaleX number + * @param scaleY number + * @param scaleZ number + * @param offsetX number + * @param offsetY number + * @param offsetZ number + * @param vType number + * @param tType number + * @param Axis number + * @return nil * * enum COLVOL_TYPES { * COLVOL_TYPE_DISABLED = -1, @@ -3515,18 +3533,18 @@ int LuaSyncedCtrl::SetUnitCollisionVolumeData(lua_State* L) /*** * @function Spring.SetUnitPieceCollisionVolumeData - * @number unitID - * @number pieceIndex - * @bool enable - * @number scaleX - * @number scaleY - * @number scaleZ - * @number offsetX - * @number offsetY - * @number offsetZ - * @number[opt] volumeType - * @number[opt] primaryAxis - * @treturn nil + * @param unitID integer + * @param pieceIndex number + * @param enable boolean + * @param scaleX number + * @param scaleY number + * @param scaleZ number + * @param offsetX number + * @param offsetY number + * @param offsetZ number + * @param volumeType number? + * @param primaryAxis number? + * @return nil */ int LuaSyncedCtrl::SetUnitPieceCollisionVolumeData(lua_State* L) { @@ -3537,10 +3555,10 @@ int LuaSyncedCtrl::SetUnitPieceCollisionVolumeData(lua_State* L) /*** * * @function Spring.SetUnitPieceVisible - * @number unitID - * @number pieceIndex - * @bool visible - * @treturn nil + * @param unitID integer + * @param pieceIndex number + * @param visible boolean + * @return nil */ int LuaSyncedCtrl::SetUnitPieceVisible(lua_State* L) { @@ -3550,10 +3568,10 @@ int LuaSyncedCtrl::SetUnitPieceVisible(lua_State* L) /*** * @function Spring.SetUnitSensorRadius - * @number unitID - * @string type "los" | "airLos" | "radar" | "sonar" | "seismic" | "radarJammer" | "sonarJammer" - * @number radius - * @treturn ?nil|number newRadius + * @param unitID integer + * @param type "los"|"airLos"|"radar"|"sonar"|"seismic"|"radarJammer"|"sonarJammer" + * @param radius number + * @return number? New radius, or `nil` if unit is invalid. */ int LuaSyncedCtrl::SetUnitSensorRadius(lua_State* L) { @@ -3605,15 +3623,15 @@ int LuaSyncedCtrl::SetUnitSensorRadius(lua_State* L) * native "is under cursor" checks and some Lua interfaces. * * @function Spring.SetUnitPosErrorParams - * @number unitID - * @number posErrorVectorX - * @number posErrorVectorY - * @number posErrorVectorZ - * @number posErrorDeltaX - * @number posErrorDeltaY - * @number posErrorDeltaZ - * @number[opt] nextPosErrorUpdate - * @treturn nil + * @param unitID integer + * @param posErrorVectorX number + * @param posErrorVectorY number + * @param posErrorVectorZ number + * @param posErrorDeltaX number + * @param posErrorDeltaY number + * @param posErrorDeltaZ number + * @param nextPosErrorUpdate number? + * @return nil */ int LuaSyncedCtrl::SetUnitPosErrorParams(lua_State* L) { @@ -3641,14 +3659,14 @@ int LuaSyncedCtrl::SetUnitPosErrorParams(lua_State* L) /*** Used by default commands to get in build-, attackrange etc. * * @function Spring.SetUnitMoveGoal - * @number unitID - * @number goalX - * @number goalY - * @number goalZ - * @number[opt] goalRadius - * @number[opt] moveSpeed - * @bool[opt] moveRaw - * @treturn nil + * @param unitID integer + * @param goalX number + * @param goalY number + * @param goalZ number + * @param goalRadius number? + * @param moveSpeed number? + * @param moveRaw boolean? + * @return nil */ int LuaSyncedCtrl::SetUnitMoveGoal(lua_State* L) { @@ -3678,12 +3696,12 @@ int LuaSyncedCtrl::SetUnitMoveGoal(lua_State* L) /*** Used in conjunction with Spring.UnitAttach et al. to re-implement old airbase & fuel system in Lua. * * @function Spring.SetUnitLandGoal - * @number unitID - * @number goalX - * @number goalY - * @number goalZ - * @number[opt] goalRadius - * @treturn nil + * @param unitID integer + * @param goalX number + * @param goalY number + * @param goalZ number + * @param goalRadius number? + * @return nil */ int LuaSyncedCtrl::SetUnitLandGoal(lua_State* L) { @@ -3707,8 +3725,8 @@ int LuaSyncedCtrl::SetUnitLandGoal(lua_State* L) /*** * @function Spring.ClearUnitGoal - * @number unitID - * @treturn nil + * @param unitID integer + * @return nil */ int LuaSyncedCtrl::ClearUnitGoal(lua_State* L) { @@ -3724,20 +3742,20 @@ int LuaSyncedCtrl::ClearUnitGoal(lua_State* L) /*** * @function Spring.SetUnitPhysics - * @number unitID - * @number posX - * @number posY - * @number posZ - * @number velX - * @number velY - * @number velZ - * @number rotX - * @number rotY - * @number rotZ - * @number dragX - * @number dragY - * @number dragZ - * @treturn nil + * @param unitID integer + * @param posX number + * @param posY number + * @param posZ number + * @param velX number + * @param velY number + * @param velZ number + * @param rotX number + * @param rotY number + * @param rotZ number + * @param dragX number + * @param dragY number + * @param dragZ number + * @return nil */ int LuaSyncedCtrl::SetUnitPhysics(lua_State* L) { @@ -3746,9 +3764,9 @@ int LuaSyncedCtrl::SetUnitPhysics(lua_State* L) /*** * @function Spring.SetUnitMass - * @number unitID - * @number mass - * @treturn nil + * @param unitID integer + * @param mass number + * @return nil */ int LuaSyncedCtrl::SetUnitMass(lua_State* L) { @@ -3761,11 +3779,11 @@ int LuaSyncedCtrl::SetUnitMass(lua_State* L) * * Sets a unit's position in 2D, at terrain height. * - * @number unitID - * @number x - * @number z - * @bool[opt=false] floating If true, over water the position is on surface. If false, on seafloor. - * @treturn nil + * @param unitID integer + * @param x number + * @param z number + * @param floating boolean? (Default: false) If true, over water the position is on surface. If false, on seafloor. + * @return nil */ @@ -3774,11 +3792,11 @@ int LuaSyncedCtrl::SetUnitMass(lua_State* L) * * Sets a unit's position in 3D, at an arbitrary height. * - * @number unitID - * @number x - * @number y - * @number z - * @treturn nil + * @param unitID integer + * @param x number + * @param y number + * @param z number + * @return nil */ int LuaSyncedCtrl::SetUnitPosition(lua_State* L) { @@ -3813,11 +3831,11 @@ int LuaSyncedCtrl::SetUnitPosition(lua_State* L) /*** * @function Spring.SetUnitRotation - * @number unitID - * @number yaw - * @number pitch - * @number roll - * @treturn nil + * @param unitID integer + * @param yaw number + * @param pitch number + * @param roll number + * @return nil */ int LuaSyncedCtrl::SetUnitRotation(lua_State* L) { @@ -3827,11 +3845,11 @@ int LuaSyncedCtrl::SetUnitRotation(lua_State* L) /*** * @function Spring.SetUnitDirection - * @number unitID - * @number x - * @number y - * @number z - * @treturn nil + * @param unitID integer + * @param x number + * @param y number + * @param z number + * @return nil */ int LuaSyncedCtrl::SetUnitDirection(lua_State* L) { @@ -3841,12 +3859,12 @@ int LuaSyncedCtrl::SetUnitDirection(lua_State* L) /*** * @function Spring.SetUnitHeadingAndUpDir * Use this call to set up unit direction in a robust way. Heading (-32768 to 32767) represents a 2D (xz plane) unit orientation if unit was completely upright, new {upx,upy,upz} direction will be used as new "up" vector, the rotation set by "heading" will remain preserved. - * @number unitID - * @number heading - * @number upx - * @number upy - * @number upz - * @treturn nil + * @param unitID integer + * @param heading number + * @param upx number + * @param upy number + * @param upz number + * @return nil */ int LuaSyncedCtrl::SetUnitHeadingAndUpDir(lua_State* L) { @@ -3855,11 +3873,11 @@ int LuaSyncedCtrl::SetUnitHeadingAndUpDir(lua_State* L) /*** * @function Spring.SetUnitVelocity - * @number unitID - * @number velX - * @number velY - * @number velZ - * @treturn nil + * @param unitID integer + * @param velX number + * @param velY number + * @param velZ number + * @return nil */ int LuaSyncedCtrl::SetUnitVelocity(lua_State* L) { @@ -3870,14 +3888,14 @@ int LuaSyncedCtrl::SetUnitVelocity(lua_State* L) /*** * * @function Spring.SetFactoryBuggerOff - * @number unitID - * @bool[opt] buggerOff - * @number[opt] offset - * @number[opt] radius - * @number[opt] relHeading - * @bool[opt] spherical - * @bool[opt] forced - * @treturn nil|number buggerOff + * @param unitID integer + * @param buggerOff boolean? + * @param offset number? + * @param radius number? + * @param relHeading number? + * @param spherical boolean? + * @param forced boolean? + * @return nil|number buggerOff */ int LuaSyncedCtrl::SetFactoryBuggerOff(lua_State* L) { @@ -3904,16 +3922,16 @@ int LuaSyncedCtrl::SetFactoryBuggerOff(lua_State* L) /*** * * @function Spring.BuggerOff - * @number x - * @number y - * @number[opt] z uses ground height when unspecified - * @number radius - * @number teamID - * @bool[opt=true] spherical - * @bool[opt=true] forced - * @number[opt] excludeUnitID - * @tparam[opt] {[number],...} excludeUnitDefIDs - * @treturn nil + * @param x number + * @param y number + * @param z number? uses ground height when unspecified + * @param radius number + * @param teamID integer + * @param spherical boolean? (Default: true) + * @param forced boolean? (Default: true) + * @param excludeUnitID integer? + * @param excludeUnitDefIDs number[]? + * @return nil */ int LuaSyncedCtrl::BuggerOff(lua_State* L) { @@ -3946,15 +3964,15 @@ int LuaSyncedCtrl::BuggerOff(lua_State* L) /*** * @function Spring.AddUnitDamage * - * @number unitID - * @number damage - * @number[opt=0] paralyze equals to the paralyzetime in the WeaponDef. - * @number[opt=-1] attackerID - * @number[opt=-1] weaponID - * @number[opt] impulseX - * @number[opt] impulseY - * @number[opt] impulseZ - * @treturn nil + * @param unitID integer + * @param damage number + * @param paralyze number? (Default: 0) equals to the paralyzetime in the WeaponDef. + * @param attackerID integer? (Default: -1) + * @param weaponID integer? (Default: -1) + * @param impulseX number? + * @param impulseY number? + * @param impulseZ number? + * @return nil */ int LuaSyncedCtrl::AddUnitDamage(lua_State* L) { @@ -3997,12 +4015,12 @@ int LuaSyncedCtrl::AddUnitDamage(lua_State* L) /*** * @function Spring.AddUnitImpulse - * @number unitID - * @number x - * @number y - * @number z - * @number[opt] decayRate - * @treturn nil + * @param unitID integer + * @param x number + * @param y number + * @param z number + * @param decayRate number? + * @return nil */ int LuaSyncedCtrl::AddUnitImpulse(lua_State* L) { @@ -4022,9 +4040,9 @@ int LuaSyncedCtrl::AddUnitImpulse(lua_State* L) /*** * @function Spring.AddUnitSeismicPing - * @number unitID - * @number pindSize - * @treturn nil + * @param unitID integer + * @param pindSize number + * @return nil */ int LuaSyncedCtrl::AddUnitSeismicPing(lua_State* L) { @@ -4042,10 +4060,10 @@ int LuaSyncedCtrl::AddUnitSeismicPing(lua_State* L) /*** * @function Spring.AddUnitResource - * @number unitID - * @string resource "m" | "e" - * @number amount - * @treturn nil + * @param unitID integer + * @param resource string "m" | "e" + * @param amount number + * @return nil */ int LuaSyncedCtrl::AddUnitResource(lua_State* L) { @@ -4068,20 +4086,21 @@ int LuaSyncedCtrl::AddUnitResource(lua_State* L) return 0; } +/* /*** * @function Spring.UseUnitResource - * @number unitID - * @string resource "m" | "e" - * @number amount - * @treturn ?nil|bool okay + * @param unitID integer + * @param resource ResourceName + * @param amount number + * @return boolean? okay */ /*** * @function Spring.UseUnitResource - * @number unitID - * @tparam {[string]=number,...} resources where keys are one of "m"|"metal"|"e"|"energy" and values are amounts - * @treturn ?nil|bool okay + * @param unitID integer + * @param resources ResourceUsage + * @return boolean? okay */ int LuaSyncedCtrl::UseUnitResource(lua_State* L) { @@ -4150,8 +4169,8 @@ int LuaSyncedCtrl::UseUnitResource(lua_State* L) /*** * * @function Spring.AddObjectDecal - * @number unitID - * @treturn nil + * @param unitID integer + * @return nil */ int LuaSyncedCtrl::AddObjectDecal(lua_State* L) { @@ -4167,8 +4186,8 @@ int LuaSyncedCtrl::AddObjectDecal(lua_State* L) /*** * @function Spring.RemoveObjectDecal - * @number unitID - * @treturn nil + * @param unitID integer + * @return nil */ int LuaSyncedCtrl::RemoveObjectDecal(lua_State* L) { @@ -4190,9 +4209,9 @@ int LuaSyncedCtrl::RemoveObjectDecal(lua_State* L) /*** * @function Spring.AddGrass - * @number x - * @number z - * @treturn nil + * @param x number + * @param z number + * @return nil */ int LuaSyncedCtrl::AddGrass(lua_State* L) { @@ -4205,9 +4224,9 @@ int LuaSyncedCtrl::AddGrass(lua_State* L) /*** * @function Spring.RemoveGrass - * @number x - * @number z - * @treturn nil + * @param x number + * @param z number + * @return nil */ int LuaSyncedCtrl::RemoveGrass(lua_State* L) { @@ -4226,14 +4245,14 @@ int LuaSyncedCtrl::RemoveGrass(lua_State* L) /*** * @function Spring.CreateFeature - * @tparam string|number featureDef name or id - * @number x - * @number y - * @number z - * @number[opt] heading - * @number[opt] AllyTeamID - * @number[opt] featureID - * @treturn number featureID + * @param featureDef string|number name or id + * @param x number + * @param y number + * @param z number + * @param heading number? + * @param AllyTeamID integer? + * @param featureID integer? + * @return number featureID */ int LuaSyncedCtrl::CreateFeature(lua_State* L) { @@ -4314,8 +4333,8 @@ int LuaSyncedCtrl::CreateFeature(lua_State* L) /*** * @function Spring.DestroyFeature - * @number featureDefID - * @treturn nil + * @param featureDefID integer + * @return nil */ int LuaSyncedCtrl::DestroyFeature(lua_State* L) { @@ -4338,9 +4357,9 @@ int LuaSyncedCtrl::DestroyFeature(lua_State* L) /*** Feature Control * * @function Spring.TransferFeature - * @number featureDefID - * @number teamID - * @treturn nil + * @param featureDefID integer + * @param teamID integer + * @return nil */ int LuaSyncedCtrl::TransferFeature(lua_State* L) { @@ -4360,9 +4379,9 @@ int LuaSyncedCtrl::TransferFeature(lua_State* L) /*** * @function Spring.SetFeatureAlwaysVisible - * @number featureID - * @bool enable - * @treturn nil + * @param featureID integer + * @param enable boolean + * @return nil */ int LuaSyncedCtrl::SetFeatureAlwaysVisible(lua_State* L) { @@ -4372,9 +4391,9 @@ int LuaSyncedCtrl::SetFeatureAlwaysVisible(lua_State* L) /*** * * @function Spring.SetFeatureUseAirLos - * @number featureID - * @bool useAirLos - * @treturn nil + * @param featureID integer + * @param useAirLos boolean + * @return nil */ int LuaSyncedCtrl::SetFeatureUseAirLos(lua_State* L) { @@ -4384,9 +4403,9 @@ int LuaSyncedCtrl::SetFeatureUseAirLos(lua_State* L) /*** * @function Spring.SetFeatureHealth - * @number featureID - * @number health - * @treturn nil + * @param featureID integer + * @param health number + * @return nil */ int LuaSyncedCtrl::SetFeatureHealth(lua_State* L) { @@ -4403,9 +4422,9 @@ int LuaSyncedCtrl::SetFeatureHealth(lua_State* L) /*** * * @function Spring.SetFeatureMaxHealth - * @number featureID - * @number maxHealth minimum 0.1 - * @treturn nil + * @param featureID integer + * @param maxHealth number minimum 0.1 + * @return nil */ int LuaSyncedCtrl::SetFeatureMaxHealth(lua_State* L) { @@ -4422,9 +4441,9 @@ int LuaSyncedCtrl::SetFeatureMaxHealth(lua_State* L) /*** * @function Spring.SetFeatureReclaim - * @number featureID - * @number reclaimLeft - * @treturn nil + * @param featureID integer + * @param reclaimLeft number + * @return nil */ int LuaSyncedCtrl::SetFeatureReclaim(lua_State* L) { @@ -4439,14 +4458,14 @@ int LuaSyncedCtrl::SetFeatureReclaim(lua_State* L) /*** * @function Spring.SetFeatureResources - * @number featureID - * @number metal - * @number energy - * @number[opt] reclaimTime - * @number[opt] reclaimLeft - * @number[opt] featureDefMetal - * @number[opt] featureDefEnergy - * @treturn nil + * @param featureID integer + * @param metal number + * @param energy number + * @param reclaimTime number? + * @param reclaimLeft number? + * @param featureDefMetal number? + * @param featureDefEnergy number? + * @return nil */ int LuaSyncedCtrl::SetFeatureResources(lua_State* L) { @@ -4469,19 +4488,11 @@ int LuaSyncedCtrl::SetFeatureResources(lua_State* L) /*** * @function Spring.SetFeatureResurrect * - * Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing -1. - * The level of progress can now be set via the additional 4th param. - * Possible values for facing are: - * "south" | "s" | 0 - * "east" | "e" | 1 - * "north" | "n" | 2 - * "west" | "w" | 3 - * - * @number featureID - * @tparam string|number unitDef id or name - * @tparam[opt] string|number facing - * @number[opt] progress - * @treturn nil + * @param featureID integer + * @param unitDef string|integer Can be a number id or a string name, this allows cancelling ressurection by passing `-1`. + * @param facing Facing? (Default: `"south"`) + * @param progress number? Set the level of progress. + * @return nil */ int LuaSyncedCtrl::SetFeatureResurrect(lua_State* L) { @@ -4529,13 +4540,13 @@ int LuaSyncedCtrl::SetFeatureResurrect(lua_State* L) * * For example use `Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)` to unlock all movement prior to making `Spring.SetFeatureVelocity` calls. * - * @number featureID - * @bool[opt] enable - * @number[opt] arg1 - * @number[opt] arg2 - * @number[opt] argn + * @param featureID integer + * @param enable boolean? + * @param arg1 number? + * @param arg2 number? + * @param argn number? * - * @treturn nil + * @return nil * */ int LuaSyncedCtrl::SetFeatureMoveCtrl(lua_State* L) @@ -4570,20 +4581,20 @@ int LuaSyncedCtrl::SetFeatureMoveCtrl(lua_State* L) /*** * @function Spring.SetFeaturePhysics - * @number featureID - * @number posX - * @number posY - * @number posZ - * @number velX - * @number velY - * @number velZ - * @number rotX - * @number rotY - * @number rotZ - * @number dragX - * @number dragY - * @number dragZ - * @treturn nil + * @param featureID integer + * @param posX number + * @param posY number + * @param posZ number + * @param velX number + * @param velY number + * @param velZ number + * @param rotX number + * @param rotY number + * @param rotZ number + * @param dragX number + * @param dragY number + * @param dragZ number + * @return nil */ int LuaSyncedCtrl::SetFeaturePhysics(lua_State* L) { @@ -4593,9 +4604,9 @@ int LuaSyncedCtrl::SetFeaturePhysics(lua_State* L) /*** * @function Spring.SetFeatureMass - * @number featureID - * @number mass - * @treturn nil + * @param featureID integer + * @param mass number + * @return nil */ int LuaSyncedCtrl::SetFeatureMass(lua_State* L) { @@ -4605,12 +4616,12 @@ int LuaSyncedCtrl::SetFeatureMass(lua_State* L) /*** * @function Spring.SetFeaturePosition - * @number featureID - * @number x - * @number y - * @number z - * @bool[opt] snapToGround - * @treturn nil + * @param featureID integer + * @param x number + * @param y number + * @param z number + * @param snapToGround boolean? + * @return nil */ int LuaSyncedCtrl::SetFeaturePosition(lua_State* L) { @@ -4631,11 +4642,11 @@ int LuaSyncedCtrl::SetFeaturePosition(lua_State* L) /*** * @function Spring.SetFeatureRotation - * @number featureID - * @number rotX - * @number rotY - * @number rotZ - * @treturn nil + * @param featureID integer + * @param rotX number + * @param rotY number + * @param rotZ number + * @return nil */ int LuaSyncedCtrl::SetFeatureRotation(lua_State* L) { @@ -4645,11 +4656,11 @@ int LuaSyncedCtrl::SetFeatureRotation(lua_State* L) /*** * @function Spring.SetFeatureDirection - * @number featureID - * @number dirX - * @number dirY - * @number dirZ - * @treturn nil + * @param featureID integer + * @param dirX number + * @param dirY number + * @param dirZ number + * @return nil */ int LuaSyncedCtrl::SetFeatureDirection(lua_State* L) { @@ -4659,12 +4670,12 @@ int LuaSyncedCtrl::SetFeatureDirection(lua_State* L) /*** * @function Spring.SetFeatureHeadingAndUpDir * Use this call to set up feature direction in a robust way. Heading (-32768 to 32767) represents a 2D (xz plane) feature orientation if feature was completely upright, new {upx,upy,upz} direction will be used as new "up" vector, the rotation set by "heading" will remain preserved. - * @number featureID - * @number heading - * @number upx - * @number upy - * @number upz - * @treturn nil + * @param featureID integer + * @param heading number + * @param upx number + * @param upy number + * @param upz number + * @return nil */ int LuaSyncedCtrl::SetFeatureHeadingAndUpDir(lua_State* L) { @@ -4673,11 +4684,11 @@ int LuaSyncedCtrl::SetFeatureHeadingAndUpDir(lua_State* L) /*** * @function Spring.SetFeatureVelocity - * @number featureID - * @number velX - * @number velY - * @number velZ - * @treturn nil + * @param featureID integer + * @param velX number + * @param velY number + * @param velZ number + * @return nil */ int LuaSyncedCtrl::SetFeatureVelocity(lua_State* L) { @@ -4687,15 +4698,15 @@ int LuaSyncedCtrl::SetFeatureVelocity(lua_State* L) /*** * @function Spring.SetFeatureBlocking - * @number featureID - * @bool isBlocking - * @bool isSolidObjectCollidable - * @bool isProjectileCollidable - * @bool isRaySegmentCollidable - * @bool crushable - * @bool blockEnemyPushing - * @bool blockHeightChanges - * @treturn nil + * @param featureID integer + * @param isBlocking boolean + * @param isSolidObjectCollidable boolean + * @param isProjectileCollidable boolean + * @param isRaySegmentCollidable boolean + * @param crushable boolean + * @param blockEnemyPushing boolean + * @param blockHeightChanges boolean + * @return nil */ int LuaSyncedCtrl::SetFeatureBlocking(lua_State* L) { @@ -4705,9 +4716,9 @@ int LuaSyncedCtrl::SetFeatureBlocking(lua_State* L) /*** * @function Spring.SetFeatureNoSelect - * @number featureID - * @bool noSelect - * @treturn nil + * @param featureID integer + * @param noSelect boolean + * @return nil */ int LuaSyncedCtrl::SetFeatureNoSelect(lua_State* L) { @@ -4726,15 +4737,15 @@ int LuaSyncedCtrl::SetFeatureNoSelect(lua_State* L) * * Check `Spring.SetUnitMidAndAimPos` for further explanation of the arguments. * - * @number featureID - * @number mpX - * @number mpY - * @number mpZ - * @number apX - * @number apY - * @number apZ - * @bool[opt] relative - * @treturn bool success + * @param featureID integer + * @param mpX number + * @param mpY number + * @param mpZ number + * @param apX number + * @param apY number + * @param apZ number + * @param relative boolean? + * @return boolean success */ int LuaSyncedCtrl::SetFeatureMidAndAimPos(lua_State* L) { @@ -4774,10 +4785,10 @@ int LuaSyncedCtrl::SetFeatureMidAndAimPos(lua_State* L) /*** * @function Spring.SetFeatureRadiusAndHeight - * @number featureID - * @number radius - * @number height - * @treturn bool success + * @param featureID integer + * @param radius number + * @param height number + * @return boolean success */ int LuaSyncedCtrl::SetFeatureRadiusAndHeight(lua_State* L) { @@ -4812,17 +4823,17 @@ int LuaSyncedCtrl::SetFeatureRadiusAndHeight(lua_State* L) * * Check `Spring.SetUnitCollisionVolumeData` for further explanation of the arguments. * - * @number featureID - * @number scaleX - * @number scaleY - * @number scaleZ - * @number offsetX - * @number offsetY - * @number offsetZ - * @number vType - * @number tType - * @number Axis - * @treturn nil + * @param featureID integer + * @param scaleX number + * @param scaleY number + * @param scaleZ number + * @param offsetX number + * @param offsetY number + * @param offsetZ number + * @param vType number + * @param tType number + * @param Axis number + * @return nil */ int LuaSyncedCtrl::SetFeatureCollisionVolumeData(lua_State* L) { @@ -4832,19 +4843,19 @@ int LuaSyncedCtrl::SetFeatureCollisionVolumeData(lua_State* L) /*** * @function Spring.SetFeaturePieceCollisionVolumeData - * @number featureID - * @number pieceIndex - * @bool enable - * @number scaleX - * @number scaleY - * @number scaleZ - * @number offsetX - * @number offsetY - * @number offsetZ - * @number Axis - * @number volumeType - * @number[opt] primaryAxis - * @treturn nil + * @param featureID integer + * @param pieceIndex number + * @param enable boolean + * @param scaleX number + * @param scaleY number + * @param scaleZ number + * @param offsetX number + * @param offsetY number + * @param offsetZ number + * @param Axis number + * @param volumeType number + * @param primaryAxis number? + * @return nil */ int LuaSyncedCtrl::SetFeaturePieceCollisionVolumeData(lua_State* L) { @@ -4854,10 +4865,10 @@ int LuaSyncedCtrl::SetFeaturePieceCollisionVolumeData(lua_State* L) /*** * * @function Spring.SetFeaturePieceVisible - * @number featureID - * @number pieceIndex - * @bool visible - * @treturn nil + * @param featureID integer + * @param pieceIndex number + * @param visible boolean + * @return nil */ int LuaSyncedCtrl::SetFeaturePieceVisible(lua_State* L) { @@ -4870,44 +4881,28 @@ int LuaSyncedCtrl::SetFeaturePieceVisible(lua_State* L) ******************************************************************************/ /*** - * @table projectileParams - * @tparam table pos - * @number pos.x - * @number pos.y - * @number pos.z - * @tparam table end - * @number end.x - * @number end.y - * @number end.z - * @tparam table speed - * @number speed.x - * @number speed.y - * @number speed.z - * @tparam table spread - * @number spread.x - * @number spread.y - * @number spread.z - * @tparam table error - * @number error.x - * @number error.y - * @number error.z - * @number owner - * @number team - * @number ttl - * @number gravity - * @number tracking - * @number maxRange - * @number startAlpha - * @number endAlpha - * @string model - * @string cegTag + * @class ProjectileParams + * @field pos float3 + * @field speed float3 + * @field spread float3 + * @field error float3 + * @field owner integer + * @field team integer + * @field ttl number + * @field gravity number + * @field tracking number + * @field maxRange number + * @field startAlpha number + * @field endAlpha number + * @field model string + * @field cegTag string */ /*** * @function Spring.SetProjectileAlwaysVisible - * @number projectileID - * @bool alwaysVisible - * @treturn nil + * @param projectileID integer + * @param alwaysVisible boolean + * @return nil */ int LuaSyncedCtrl::SetProjectileAlwaysVisible(lua_State* L) { @@ -4918,9 +4913,9 @@ int LuaSyncedCtrl::SetProjectileAlwaysVisible(lua_State* L) /*** * * @function Spring.SetProjectileUseAirLos - * @number projectileID - * @bool useAirLos - * @treturn nil + * @param projectileID integer + * @param useAirLos boolean + * @return nil */ int LuaSyncedCtrl::SetProjectileUseAirLos(lua_State* L) { @@ -4931,9 +4926,9 @@ int LuaSyncedCtrl::SetProjectileUseAirLos(lua_State* L) /*** * Disables engine movecontrol, so lua can fully control the physics. * @function Spring.SetProjectileMoveControl - * @number projectileID - * @bool enable - * @treturn nil + * @param projectileID integer + * @param enable boolean + * @return nil */ int LuaSyncedCtrl::SetProjectileMoveControl(lua_State* L) { @@ -4950,11 +4945,11 @@ int LuaSyncedCtrl::SetProjectileMoveControl(lua_State* L) /*** * @function Spring.SetProjectilePosition - * @number projectileID - * @number[opt=0] posX - * @number[opt=0] posY - * @number[opt=0] posZ - * @treturn nil + * @param projectileID integer + * @param posX number? (Default: 0) + * @param posY number? (Default: 0) + * @param posZ number? (Default: 0) + * @return nil */ int LuaSyncedCtrl::SetProjectilePosition(lua_State* L) { @@ -4972,11 +4967,11 @@ int LuaSyncedCtrl::SetProjectilePosition(lua_State* L) /*** * @function Spring.SetProjectileVelocity - * @number projectileID - * @number[opt=0] velX - * @number[opt=0] velY - * @number[opt=0] velZ - * @treturn nil + * @param projectileID integer + * @param velX number? (Default: 0) + * @param velY number? (Default: 0) + * @param velZ number? (Default: 0) + * @return nil * */ int LuaSyncedCtrl::SetProjectileVelocity(lua_State* L) @@ -4986,8 +4981,8 @@ int LuaSyncedCtrl::SetProjectileVelocity(lua_State* L) /*** * @function Spring.SetProjectileCollision - * @number projectileID - * @treturn nil + * @param projectileID integer + * @return nil */ int LuaSyncedCtrl::SetProjectileCollision(lua_State* L) { @@ -5013,11 +5008,11 @@ int LuaSyncedCtrl::SetProjectileCollision(lua_State* L) * string.byte('f') := FEATURE * string.byte('p') := PROJECTILE * - * @number projectileID - * @number[opt=0] arg1 targetID or posX - * @number[opt=0] arg2 targetType or posY - * @number[opt=0] posZ - * @treturn ?nil|bool validTarget + * @param projectileID integer + * @param arg1 number? (Default: 0) targetID or posX + * @param arg2 number? (Default: 0) targetType or posY + * @param posZ number? (Default: 0) + * @return boolean? validTarget */ int LuaSyncedCtrl::SetProjectileTarget(lua_State* L) { @@ -5091,9 +5086,9 @@ int LuaSyncedCtrl::SetProjectileTarget(lua_State* L) /*** * @function Spring.SetProjectileTimeToLive - * @number projectileID - * @number ttl remaining time to live in frames - * @treturn nil + * @param projectileID integer + * @param ttl number Remaining time to live in frames + * @return nil */ int LuaSyncedCtrl::SetProjectileTimeToLive(lua_State* L) { @@ -5113,8 +5108,8 @@ int LuaSyncedCtrl::SetProjectileTimeToLive(lua_State* L) /*** * @function Spring.SetProjectileIsIntercepted - * @number projectileID - * @treturn nil + * @param projectileID integer + * @return nil */ int LuaSyncedCtrl::SetProjectileIsIntercepted(lua_State* L) { @@ -5133,11 +5128,11 @@ int LuaSyncedCtrl::SetProjectileIsIntercepted(lua_State* L) /*** * @function Spring.SetProjectileDamages - * @number unitID - * @number weaponNum - * @string key - * @number value - * @treturn nil + * @param unitID integer + * @param weaponNum number + * @param key string + * @param value number + * @return nil */ int LuaSyncedCtrl::SetProjectileDamages(lua_State* L) { @@ -5170,9 +5165,9 @@ int LuaSyncedCtrl::SetProjectileDamages(lua_State* L) /*** * @function Spring.SetProjectileIgnoreTrackingError - * @number projectileID - * @bool ignore - * @treturn nil + * @param projectileID integer + * @param ignore boolean + * @return nil */ int LuaSyncedCtrl::SetProjectileIgnoreTrackingError(lua_State* L) { @@ -5200,9 +5195,9 @@ int LuaSyncedCtrl::SetProjectileIgnoreTrackingError(lua_State* L) /*** * @function Spring.SetProjectileGravity - * @number projectileID - * @number[opt=0] grav - * @treturn nil + * @param projectileID integer + * @param grav number? (Default: 0) + * @return nil */ int LuaSyncedCtrl::SetProjectileGravity(lua_State* L) { @@ -5223,14 +5218,14 @@ int LuaSyncedCtrl::SetProjectileSpinVec(lua_State* L) { return 0; } // FIXME: DE /*** * @function Spring.SetPieceProjectileParams - * @number projectileID - * @number[opt] explosionFlags - * @number[opt] spinAngle - * @number[opt] spinSpeed - * @number[opt] spinVectorX - * @number[opt] spinVectorY - * @number[opt] spinVectorZ - * @treturn nil + * @param projectileID integer + * @param explosionFlags number? + * @param spinAngle number? + * @param spinSpeed number? + * @param spinVectorX number? + * @param spinVectorY number? + * @param spinVectorZ number? + * @return nil */ int LuaSyncedCtrl::SetPieceProjectileParams(lua_State* L) { @@ -5255,9 +5250,9 @@ int LuaSyncedCtrl::SetPieceProjectileParams(lua_State* L) // /*** * @function Spring.SetProjectileCEG - * @number projectileID - * @string ceg_name - * @treturn nil + * @param projectileID integer + * @param ceg_name string + * @return nil */ int LuaSyncedCtrl::SetProjectileCEG(lua_State* L) { @@ -5292,34 +5287,9 @@ int LuaSyncedCtrl::SetProjectileCEG(lua_State* L) */ -/*** Command Options params - * - * @table cmdOpts - * - * @tparam bool right Right mouse key pressed - * @tparam bool alt Alt key pressed - * @tparam bool ctrl Ctrl key pressed - * @tparam bool shift Shift key pressed - */ - - -/*** Command spec - * - * @table cmdSpec - * - * Used when assigning multiple commands at once - * - * @number cmdID - * @tparam {number,...}|nil params - * @tparam cmdOpts|nil options - */ - - /*** - * * @function Spring.UnitFinishCommand - * @number unitID - * @treturn nil + * @param unitID integer */ int LuaSyncedCtrl::UnitFinishCommand(lua_State* L) { @@ -5338,11 +5308,11 @@ int LuaSyncedCtrl::UnitFinishCommand(lua_State* L) /*** * @function Spring.GiveOrderToUnit - * @number unitID - * @number cmdID - * @tparam {number,...}|nil params - * @tparam cmdOpts|nil options - * @treturn bool unitOrdered + * @param unitID integer + * @param cmdID integer + * @param params number[]? + * @param options CommandOptions? + * @return boolean unitOrdered */ int LuaSyncedCtrl::GiveOrderToUnit(lua_State* L) { @@ -5374,11 +5344,11 @@ int LuaSyncedCtrl::GiveOrderToUnit(lua_State* L) /*** * @function Spring.GiveOrderToUnitMap - * @tparam {[number]=table,...} unitMap table with unitIDs as keys - * @number cmdID - * @tparam {number,...}|nil params - * @tparam cmdOpts|nil options - * @treturn number unitsOrdered + * @param unitMap table table with unitIDs as keys + * @param cmdID integer + * @param params number[]? + * @param options CommandOptions? + * @return number unitsOrdered */ int LuaSyncedCtrl::GiveOrderToUnitMap(lua_State* L) { @@ -5417,11 +5387,11 @@ int LuaSyncedCtrl::GiveOrderToUnitMap(lua_State* L) /*** * * @function Spring.GiveOrderToUnitArray - * @tparam {number,...} unitIDs - * @number cmdID - * @tparam {number,...}|nil params - * @tparam cmdOpts|nil options - * @treturn number unitsOrdered + * @param unitIDs number[] + * @param cmdID integer + * @param params number[]? + * @param options CommandOptions? + * @return number unitsOrdered */ int LuaSyncedCtrl::GiveOrderToUnitArray(lua_State* L) { @@ -5462,9 +5432,9 @@ int LuaSyncedCtrl::GiveOrderToUnitArray(lua_State* L) /*** * * @function Spring.GiveOrderArrayToUnit - * @number unitID - * @tparam {cmdSpec,...} cmdArray - * @treturn bool ordersGiven + * @param unitID integer + * @param cmdArray Command[] + * @return boolean ordersGiven */ int LuaSyncedCtrl::GiveOrderArrayToUnit(lua_State* L) { @@ -5502,9 +5472,9 @@ int LuaSyncedCtrl::GiveOrderArrayToUnit(lua_State* L) /*** * @function Spring.GiveOrderArrayToUnitMap - * @tparam {[number]=table} unitMap table with unitIDs as keys - * @tparam {cmdSpec,...} orderArray - * @treturn number unitsOrdered + * @param unitMap {[number]: any} table with unitIDs as keys + * @param commands Command[] + * @return number unitsOrdered */ int LuaSyncedCtrl::GiveOrderArrayToUnitMap(lua_State* L) { @@ -5544,9 +5514,9 @@ int LuaSyncedCtrl::GiveOrderArrayToUnitMap(lua_State* L) /*** * @function Spring.GiveOrderArrayToUnitArray - * @tparam {number,...} unitArray containing unitIDs - * @tparam {cmdSpec,...} orderArray - * @treturn nil + * @param unitArray number[] containing unitIDs + * @param commands Command[] + * @return nil */ int LuaSyncedCtrl::GiveOrderArrayToUnitArray(lua_State* L) { @@ -5654,12 +5624,12 @@ static inline void ParseMapParams(lua_State* L, const char* caller, /*** Set a certain height to a point or rectangle area on the world * * @function Spring.LevelHeightMap - * @number x1 - * @number z1 - * @number x2_height if y2 and height are nil then this parameter is the height - * @number[opt] z2 - * @number[opt] height - * @treturn nil + * @param x1 number + * @param z1 number + * @param x2_height number if y2 and height are nil then this parameter is the height + * @param z2 number? + * @param height number? + * @return nil */ int LuaSyncedCtrl::LevelHeightMap(lua_State* L) { @@ -5684,12 +5654,12 @@ int LuaSyncedCtrl::LevelHeightMap(lua_State* L) /*** Add a certain height to a point or rectangle area on the world * * @function Spring.AdjustHeightMap - * @number x1 - * @number y1 - * @number x2_height if y2 and height are nil then this parameter is the height - * @number[opt] y2 - * @number[opt] height - * @treturn nil + * @param x1 number + * @param y1 number + * @param x2_height number if y2 and height are nil then this parameter is the height + * @param y2 number? + * @param height number? + * @return nil */ int LuaSyncedCtrl::AdjustHeightMap(lua_State* L) { @@ -5716,12 +5686,12 @@ int LuaSyncedCtrl::AdjustHeightMap(lua_State* L) /*** Restore original map height to a point or rectangle area on the world * * @function Spring.RevertHeightMap - * @number x1 - * @number y1 - * @number x2_factor if y2 and factor are nil then this parameter is the factor - * @number[opt] y2 - * @number[opt] factor - * @treturn nil + * @param x1 number + * @param y1 number + * @param x2_factor number if y2 and factor are nil then this parameter is the factor + * @param y2 number? + * @param factor number? + * @return nil */ int LuaSyncedCtrl::RevertHeightMap(lua_State* L) { @@ -5764,10 +5734,10 @@ int LuaSyncedCtrl::RevertHeightMap(lua_State* L) /*** Can only be called in `Spring.SetHeightMapFunc` * * @function Spring.AddHeightMap - * @number x - * @number z - * @number height - * @treturn ?nil|number newHeight + * @param x number + * @param z number + * @param height number + * @return integer? newHeight */ int LuaSyncedCtrl::AddHeightMap(lua_State* L) { @@ -5812,11 +5782,11 @@ int LuaSyncedCtrl::AddHeightMap(lua_State* L) * * Can only be called in `Spring.SetHeightMapFunc`. The terraform argument is * - * @number x - * @number z - * @number height - * @number[opt=1] terraform a scaling factor. - * @treturn ?nil|number absHeightDiff =0 nothing will be changed (the terraform starts) and if =1 the terraform will be finished. + * @param x number + * @param z number + * @param height number + * @param terraform number? (Default: 1) Scaling factor. + * @return integer? absHeightDiff If `0`, nothing will be changed (the terraform starts), if `1` the terraform will be finished. * */ int LuaSyncedCtrl::SetHeightMap(lua_State* L) @@ -5870,19 +5840,20 @@ int LuaSyncedCtrl::SetHeightMap(lua_State* L) * * Example code: * - * function Spring.SetHeightMapFunc(function() - * for z=0,Game.mapSizeZ, Game.squareSize do - * for x=0,Game.mapSizeX, Game.squareSize do - * Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) ) - * end - * end - * end) - * - * @func lua_function - * @param[opt] arg1 - * @param[opt] arg2 - * @param[opt] argn - * @treturn ?nil|number absTotalHeightMapAmountChanged + * ```lua + * function Spring.SetHeightMapFunc(function() + * for z=0,Game.mapSizeZ, Game.squareSize do + * for x=0,Game.mapSizeX, Game.squareSize do + * Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) ) + * end + * end + * end) + * ``` + * + * @param luaFunction function + * @param arg number + * @param ... number + * @return integer? absTotalHeightMapAmountChanged */ int LuaSyncedCtrl::SetHeightMapFunc(lua_State* L) { @@ -5932,12 +5903,12 @@ int LuaSyncedCtrl::SetHeightMapFunc(lua_State* L) /*** Set a height to a point or rectangle area to the original map height cache * * @function Spring.LevelOriginalHeightMap - * @number x1 - * @number y1 - * @number x2_height if y2 and height are nil then this parameter is the height - * @number[opt] y2 - * @number[opt] height - * @treturn nil + * @param x1 number + * @param y1 number + * @param x2_height number if y2 and height are nil then this parameter is the height + * @param y2 number? + * @param height number? + * @return nil */ int LuaSyncedCtrl::LevelOriginalHeightMap(lua_State* L) { @@ -5961,12 +5932,12 @@ int LuaSyncedCtrl::LevelOriginalHeightMap(lua_State* L) /*** Add height to a point or rectangle area to the original map height cache * * @function Spring.AdjustOriginalHeightMap - * @number x1 - * @number y1 - * @number x2_height if y2 and height are nil then this parameter is the height - * @number[opt] y2 - * @number[opt] height - * @treturn nil + * @param x1 number + * @param y1 number + * @param x2_height number if y2 and height are nil then this parameter is the height + * @param y2 number? + * @param height number? + * @return nil */ int LuaSyncedCtrl::AdjustOriginalHeightMap(lua_State* L) { @@ -5992,12 +5963,12 @@ int LuaSyncedCtrl::AdjustOriginalHeightMap(lua_State* L) /*** Restore original map height cache to a point or rectangle area on the world * * @function Spring.RevertOriginalHeightMap - * @number x1 - * @number y1 - * @number x2_factor if y2 and factor are nil then this parameter is the factor - * @number[opt] y2 - * @number[opt] factor - * @treturn nil + * @param x1 number + * @param y1 number + * @param x2_factor number if y2 and factor are nil then this parameter is the factor + * @param y2 number? + * @param factor number? + * @return nil */ int LuaSyncedCtrl::RevertOriginalHeightMap(lua_State* L) { @@ -6042,10 +6013,10 @@ int LuaSyncedCtrl::RevertOriginalHeightMap(lua_State* L) * * Can only be called in `Spring.SetOriginalHeightMapFunc` * - * @number x - * @number y - * @number height - * @treturn nil + * @param x number + * @param y number + * @param height number + * @return nil */ int LuaSyncedCtrl::AddOriginalHeightMap(lua_State* L) { @@ -6084,11 +6055,11 @@ int LuaSyncedCtrl::AddOriginalHeightMap(lua_State* L) * * Can only be called in `Spring.SetOriginalHeightMapFunc` * - * @number x - * @number y - * @number height - * @number[opt] factor - * @treturn nil + * @param x number + * @param y number + * @param height number + * @param factor number? + * @return nil */ int LuaSyncedCtrl::SetOriginalHeightMap(lua_State* L) { @@ -6136,8 +6107,8 @@ int LuaSyncedCtrl::SetOriginalHeightMap(lua_State* L) * * Cannot recurse on itself * - * @func heightMapFunc - * @treturn nil + * @param heightMapFunc function + * @return nil */ int LuaSyncedCtrl::SetOriginalHeightMapFunc(lua_State* L) { @@ -6188,7 +6159,7 @@ static inline void ParseSmoothMeshParams(lua_State* L, const char* caller, * Heightmap changes normally take up to 25s to propagate to the smooth mesh. * Use to force a mapwide update immediately. * - * @treturn nil + * @return nil */ int LuaSyncedCtrl::RebuildSmoothMesh(lua_State* L) { @@ -6199,12 +6170,12 @@ int LuaSyncedCtrl::RebuildSmoothMesh(lua_State* L) /*** * @function Spring.LevelSmoothMesh - * @number x1 - * @number z1 - * @number[opt] x2 - * @number[opt] z2 - * @number height - * @treturn nil + * @param x1 number + * @param z1 number + * @param x2 number? + * @param z2 number? + * @param height number + * @return nil */ int LuaSyncedCtrl::LevelSmoothMesh(lua_State* L) { @@ -6225,12 +6196,12 @@ int LuaSyncedCtrl::LevelSmoothMesh(lua_State* L) /*** * @function Spring.AdjustSmoothMesh - * @number x1 - * @number z1 - * @number[opt] x2 - * @number[opt] z2 - * @number height - * @treturn nil + * @param x1 number + * @param z1 number + * @param x2 number? + * @param z2 number? + * @param height number + * @return nil */ int LuaSyncedCtrl::AdjustSmoothMesh(lua_State* L) { @@ -6251,12 +6222,12 @@ int LuaSyncedCtrl::AdjustSmoothMesh(lua_State* L) /*** * * @function Spring.RevertSmoothMesh - * @number x1 - * @number z1 - * @number[opt] x2 - * @number[opt] z2 - * @number origFactor - * @treturn nil + * @param x1 number + * @param z1 number + * @param x2 number? + * @param z2 number? + * @param origFactor number + * @return nil */ int LuaSyncedCtrl::RevertSmoothMesh(lua_State* L) { @@ -6294,10 +6265,10 @@ int LuaSyncedCtrl::RevertSmoothMesh(lua_State* L) /*** Can only be called in `Spring.SetSmoothMeshFunc`. * * @function Spring.AddSmoothMesh - * @number x - * @number z - * @number height - * @treturn ?nil|number newHeight + * @param x number + * @param z number + * @param height number + * @return number? The new height, or `nil` if coordinates are invalid. */ int LuaSyncedCtrl::AddSmoothMesh(lua_State* L) { @@ -6329,14 +6300,14 @@ int LuaSyncedCtrl::AddSmoothMesh(lua_State* L) return 1; } -/*** Can only be called in `Spring.SetSmoothMeshFunc`. +/***Can only be called in `Spring.SetSmoothMeshFunc`. * * @function Spring.SetSmoothMesh - * @number x - * @number z - * @number height - * @number[opt=1] terraform - * @treturn ?nil|number absHeightDiff + * @param x number + * @param z number + * @param height number + * @param terraform number? (Default: 1) + * @return number? The absolute height difference, or `nil` if coordinates are invalid. */ int LuaSyncedCtrl::SetSmoothMesh(lua_State* L) { @@ -6379,11 +6350,10 @@ int LuaSyncedCtrl::SetSmoothMesh(lua_State* L) /*** * @function Spring.SetSmoothMeshFunc - * @func lua_function - * @param arg1[opt] - * @param arg2[opt] - * @param argn[opt] - * @treturn ?nil|number absTotalHeightMapAmountChanged + * @param luaFunction function + * @param arg any? + * @param ... any? + * @return number? absTotalHeightMapAmountChanged */ int LuaSyncedCtrl::SetSmoothMeshFunc(lua_State* L) { @@ -6421,10 +6391,10 @@ int LuaSyncedCtrl::SetSmoothMeshFunc(lua_State* L) /*** * @function Spring.SetMapSquareTerrainType - * @number x - * @number z - * @number newType - * @treturn ?nil|number oldType + * @param x number + * @param z number + * @param newType number + * @return integer? oldType */ int LuaSyncedCtrl::SetMapSquareTerrainType(lua_State* L) { @@ -6451,12 +6421,12 @@ int LuaSyncedCtrl::SetMapSquareTerrainType(lua_State* L) /*** * @function Spring.SetTerrainTypeData - * @number typeIndex - * @number[opt=nil] speedTanks - * @number[opt=nil] speedKBOts - * @number[opt=nil] speedHovers - * @number[opt=nil] speedShips - * @treturn ?nil|bool true + * @param typeIndex number + * @param speedTanks number? (Default: nil) + * @param speedKBOts number? (Default: nil) + * @param speedHovers number? (Default: nil) + * @param speedShips number? (Default: nil) + * @return boolean? true */ int LuaSyncedCtrl::SetTerrainTypeData(lua_State* L) { @@ -6498,10 +6468,10 @@ int LuaSyncedCtrl::SetTerrainTypeData(lua_State* L) /*** * @function Spring.SetSquareBuildingMask - * @number x - * @number z - * @number mask - * @treturn nil + * @param x number + * @param z number + * @param mask number + * @return nil * * See also buildingMask unitdef tag. */ @@ -6530,9 +6500,9 @@ int LuaSyncedCtrl::SetSquareBuildingMask(lua_State* L) /*** * @function Spring.UnitWeaponFire - * @number unitID - * @number weaponID - * @treturn nil + * @param unitID integer + * @param weaponID integer + * @return nil */ int LuaSyncedCtrl::UnitWeaponFire(lua_State* L) { @@ -6553,9 +6523,9 @@ int LuaSyncedCtrl::UnitWeaponFire(lua_State* L) // NB: not permanent /*** * @function Spring.UnitWeaponHoldFire - * @number unitID - * @number weaponID - * @treturn nil + * @param unitID integer + * @param weaponID integer + * @return nil */ int LuaSyncedCtrl::UnitWeaponHoldFire(lua_State* L) { @@ -6584,8 +6554,8 @@ int LuaSyncedCtrl::UnitWeaponHoldFire(lua_State* L) * the normal update rate is set. * * @function Spring.ForceUnitCollisionUpdate - * @number unitID - * @treturn nil + * @param unitID integer + * @return nil */ int LuaSyncedCtrl::ForceUnitCollisionUpdate(lua_State* L) { @@ -6602,10 +6572,10 @@ int LuaSyncedCtrl::ForceUnitCollisionUpdate(lua_State* L) /*** * * @function Spring.UnitAttach - * @number transporterID - * @number passengerID - * @number pieceNum - * @treturn nil + * @param transporterID integer + * @param passengerID integer + * @param pieceNum number + * @return nil */ int LuaSyncedCtrl::UnitAttach(lua_State* L) { @@ -6640,8 +6610,8 @@ int LuaSyncedCtrl::UnitAttach(lua_State* L) /*** * @function Spring.UnitDetach - * @number passengerID - * @treturn nil + * @param passengerID integer + * @return nil */ int LuaSyncedCtrl::UnitDetach(lua_State* L) { @@ -6662,8 +6632,8 @@ int LuaSyncedCtrl::UnitDetach(lua_State* L) /*** * @function Spring.UnitDetachFromAir - * @number passengerID - * @treturn nil + * @param passengerID integer + * @return nil */ int LuaSyncedCtrl::UnitDetachFromAir(lua_State* L) { @@ -6695,9 +6665,9 @@ int LuaSyncedCtrl::UnitDetachFromAir(lua_State* L) /*** Disables collisions between the two units to allow colvol intersection during the approach. * * @function Spring.SetUnitLoadingTransport - * @number passengerID - * @number transportID - * @treturn nil + * @param passengerID integer + * @param transportID integer + * @return nil */ int LuaSyncedCtrl::SetUnitLoadingTransport(lua_State* L) { @@ -6725,9 +6695,9 @@ int LuaSyncedCtrl::SetUnitLoadingTransport(lua_State* L) /*** * * @function Spring.SpawnProjectile - * @number weaponDefID - * @tparam projectileParams projectileParams - * @treturn ?nil|number projectileID + * @param weaponDefID integer + * @param projectileParams ProjectileParams + * @return integer? projectileID */ int LuaSyncedCtrl::SpawnProjectile(lua_State* L) { @@ -6747,8 +6717,8 @@ int LuaSyncedCtrl::SpawnProjectile(lua_State* L) /*** Silently removes projectiles (no explosion). * * @function Spring.DeleteProjectile - * @number projectileID - * @treturn nil + * @param projectileID integer + * @return nil */ int LuaSyncedCtrl::DeleteProjectile(lua_State* L) { @@ -6869,36 +6839,37 @@ static int SetExplosionParam(lua_State* L, CExplosionParams& params, DamageArray return 0; } -/*** Parameters for explosion +/*** + * Parameters for explosion. * * Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef. * The weapondefID is only used for visuals and for passing into callins like UnitDamaged. * - * @table explosionParams - * @number weaponDef - * @number owner - * @number hitUnit - * @number hitFeature - * @number craterAreaOfEffect - * @number damageAreaOfEffect - * @number edgeEffectiveness - * @number explosionSpeed - * @number gfxMod - * @bool impactOnly - * @bool ignoreOwner - * @bool damageGround + * @class ExplosionParams + * @field weaponDef number + * @field owner number + * @field hitUnit number + * @field hitFeature number + * @field craterAreaOfEffect number + * @field damageAreaOfEffect number + * @field edgeEffectiveness number + * @field explosionSpeed number + * @field gfxMod number + * @field impactOnly boolean + * @field ignoreOwner boolean + * @field damageGround boolean */ /*** * @function Spring.SpawnExplosion - * @number[opt=0] posX - * @number[opt=0] posY - * @number[opt=0] posZ - * @number[opt=0] dirX - * @number[opt=0] dirY - * @number[opt=0] dirZ - * @tparam explosionParams explosionParams - * @treturn nil + * @param posX number? (Default: 0) + * @param posY number? (Default: 0) + * @param posZ number? (Default: 0) + * @param dirX number? (Default: 0) + * @param dirY number? (Default: 0) + * @param dirZ number? (Default: 0) + * @param explosionParams ExplosionParams + * @return nil */ int LuaSyncedCtrl::SpawnExplosion(lua_State* L) { @@ -6963,17 +6934,17 @@ int LuaSyncedCtrl::SpawnExplosion(lua_State* L) /*** * @function Spring.SpawnCEG - * @string cegname - * @number[opt=0] posX - * @number[opt=0] posY - * @number[opt=0] posZ - * @number[opt=0] dirX - * @number[opt=0] dirY - * @number[opt=0] dirZ - * @number[opt=0] radius - * @number[opt=0] damage - * @treturn ?nil|bool success - * @treturn number cegID + * @param cegname string + * @param posX number? (Default: 0) + * @param posY number? (Default: 0) + * @param posZ number? (Default: 0) + * @param dirX number? (Default: 0) + * @param dirY number? (Default: 0) + * @param dirZ number? (Default: 0) + * @param radius number? (Default: 0) + * @param damage number? (Default: 0) + * @return boolean? success + * @return number cegID */ int LuaSyncedCtrl::SpawnCEG(lua_State* L) { @@ -6996,18 +6967,18 @@ int LuaSyncedCtrl::SpawnCEG(lua_State* L) /*** Equal to the UnitScript versions of EmitSFX, but takes position and direction arguments (in either unit- or piece-space) instead of a piece index. * * @function Spring.SpawnSFX - * @number[opt=0] unitID - * @number[opt=0] sfxID - * @number[opt=0] posX - * @number[opt=0] posY - * @number[opt=0] posZ - * @number[opt=0] dirX - * @number[opt=0] dirY - * @number[opt=0] dirZ - * @number[opt=0] radius - * @number[opt=0] damage - * @bool[opt] absolute - * @treturn ?nil|bool success + * @param unitID integer? (Default: 0) + * @param sfxID integer? (Default: 0) + * @param posX number? (Default: 0) + * @param posY number? (Default: 0) + * @param posZ number? (Default: 0) + * @param dirX number? (Default: 0) + * @param dirY number? (Default: 0) + * @param dirZ number? (Default: 0) + * @param radius number? (Default: 0) + * @param damage number? (Default: 0) + * @param absolute boolean? + * @return boolean? success */ int LuaSyncedCtrl::SpawnSFX(lua_State* L) { @@ -7035,8 +7006,8 @@ int LuaSyncedCtrl::SpawnSFX(lua_State* L) /*** * @function Spring.SetNoPause - * @bool noPause - * @treturn nil + * @param noPause boolean + * @return nil */ int LuaSyncedCtrl::SetNoPause(lua_State* L) { @@ -7054,11 +7025,11 @@ int LuaSyncedCtrl::SetNoPause(lua_State* L) /*** Defines how often `Callins.UnitExperience` will be called. * * @function Spring.SetExperienceGrade - * @number expGrade - * @number[opt] ExpPowerScale - * @number[opt] ExpHealthScale - * @number[opt] ExpReloadScale - * @treturn nil + * @param expGrade number + * @param ExpPowerScale number? + * @param ExpHealthScale number? + * @param ExpReloadScale number? + * @return nil */ int LuaSyncedCtrl::SetExperienceGrade(lua_State* L) { @@ -7086,11 +7057,11 @@ int LuaSyncedCtrl::SetExperienceGrade(lua_State* L) /*** * * @function Spring.SetRadarErrorParams - * @number allyTeamID - * @number allyteamErrorSize - * @number[opt] baseErrorSize - * @number[opt] baseErrorMult - * @treturn nil + * @param allyTeamID integer + * @param allyteamErrorSize number + * @param baseErrorSize number? + * @param baseErrorMult number? + * @return nil */ int LuaSyncedCtrl::SetRadarErrorParams(lua_State* L) { @@ -7218,28 +7189,11 @@ static bool ParseCommandDescription(lua_State* L, int table, return true; } - /*** * @function Spring.EditUnitCmdDesc - * @number unitID - * @number cmdDescID - * @tparam table cmdArray structure of cmdArray: - * { - * [ id = int ], - * [ type = int ], - * [ name = string ], - * [ action = string ], - * [ tooltip = string ], - * [ texture = string ], - * [ cursor = string ], - * [ queueing = boolean ], - * [ hidden = boolean ], - * [ disabled = boolean ], - * [ showUnique = boolean ], - * [ onlyTexture = boolean ], - * [ params = { string = string, ... } ] - * } - * @treturn nil + * @param unitID integer + * @param cmdDescID integer + * @param cmdArray CommandDescription */ int LuaSyncedCtrl::EditUnitCmdDesc(lua_State* L) { @@ -7269,10 +7223,9 @@ int LuaSyncedCtrl::EditUnitCmdDesc(lua_State* L) /*** * @function Spring.InsertUnitCmdDesc - * @number unitID - * @number[opt] cmdDescID - * @tparam table cmdArray - * @treturn nil + * @param unitID integer + * @param cmdDescID integer? + * @param cmdArray CommandDescription */ int LuaSyncedCtrl::InsertUnitCmdDesc(lua_State* L) { @@ -7310,9 +7263,8 @@ int LuaSyncedCtrl::InsertUnitCmdDesc(lua_State* L) /*** * @function Spring.RemoveUnitCmdDesc - * @number unitID - * @number[opt] cmdDescID - * @treturn nil + * @param unitID integer + * @param cmdDescID integer? */ int LuaSyncedCtrl::RemoveUnitCmdDesc(lua_State* L) { @@ -7333,5 +7285,3 @@ int LuaSyncedCtrl::RemoveUnitCmdDesc(lua_State* L) unit->commandAI->RemoveCommandDescription(cmdDescIdx); return 0; } - - diff --git a/rts/Lua/LuaSyncedMoveCtrl.cpp b/rts/Lua/LuaSyncedMoveCtrl.cpp index 60ef06f106..952f45e5c2 100644 --- a/rts/Lua/LuaSyncedMoveCtrl.cpp +++ b/rts/Lua/LuaSyncedMoveCtrl.cpp @@ -25,7 +25,6 @@ /****************************************************************************** * MoveCtrl - * @module MoveCtrl * * @see rts/Lua/LuaSyncedMoveCtrl.cpp ******************************************************************************/ diff --git a/rts/Lua/LuaSyncedRead.cpp b/rts/Lua/LuaSyncedRead.cpp index ce90951a1e..031b9c9c5b 100644 --- a/rts/Lua/LuaSyncedRead.cpp +++ b/rts/Lua/LuaSyncedRead.cpp @@ -90,7 +90,6 @@ static const LuaHashString hs_n("n"); /****************************************************************************** * Synced Read * - * @module SyncedRead * @see rts/Lua/LuaSyncedRead.cpp ******************************************************************************/ @@ -124,7 +123,7 @@ bool LuaSyncedRead::PushEntries(lua_State* L) REGISTER_LUA_CFUNC(GetPlayerRulesParam); REGISTER_LUA_CFUNC(GetPlayerRulesParams); - + REGISTER_LUA_CFUNC(GetMapOption); REGISTER_LUA_CFUNC(GetMapOptions); REGISTER_LUA_CFUNC(GetModOption); @@ -755,7 +754,7 @@ static int GetRulesParam(lua_State* L, const char* caller, int index, * * @function Spring.IsCheatingEnabled * - * @treturn bool enabled + * @return boolean enabled */ int LuaSyncedRead::IsCheatingEnabled(lua_State* L) { @@ -768,7 +767,7 @@ int LuaSyncedRead::IsCheatingEnabled(lua_State* L) * * @function Spring.IsGodModeEnabled * - * @treturn bool enabled + * @return boolean enabled */ int LuaSyncedRead::IsGodModeEnabled(lua_State* L) { @@ -783,7 +782,7 @@ int LuaSyncedRead::IsGodModeEnabled(lua_State* L) * * @function Spring.IsDevLuaEnabled * - * @treturn bool enabled + * @return boolean enabled */ int LuaSyncedRead::IsDevLuaEnabled(lua_State* L) { @@ -796,7 +795,7 @@ int LuaSyncedRead::IsDevLuaEnabled(lua_State* L) * * @function Spring.IsEditDefsEnabled * - * @treturn bool enabled + * @return boolean enabled */ int LuaSyncedRead::IsEditDefsEnabled(lua_State* L) { @@ -809,7 +808,7 @@ int LuaSyncedRead::IsEditDefsEnabled(lua_State* L) * * @function Spring.IsNoCostEnabled * - * @treturn bool enabled + * @return boolean enabled */ int LuaSyncedRead::IsNoCostEnabled(lua_State* L) { @@ -822,9 +821,9 @@ int LuaSyncedRead::IsNoCostEnabled(lua_State* L) * * @function Spring.GetGlobalLos * - * @number[opt] teamID + * @param teamID integer? * - * @treturn bool enabled + * @return boolean enabled */ int LuaSyncedRead::GetGlobalLos(lua_State* L) { @@ -841,7 +840,7 @@ int LuaSyncedRead::GetGlobalLos(lua_State* L) * * @function Spring.AreHelperAIsEnabled * - * @treturn bool enabled + * @return boolean enabled */ int LuaSyncedRead::AreHelperAIsEnabled(lua_State* L) { @@ -854,7 +853,7 @@ int LuaSyncedRead::AreHelperAIsEnabled(lua_State* L) * * @function Spring.FixedAllies * - * @treturn bool|nil enabled + * @return boolean|nil enabled */ int LuaSyncedRead::FixedAllies(lua_State* L) { @@ -867,7 +866,7 @@ int LuaSyncedRead::FixedAllies(lua_State* L) * * @function Spring.IsGameOver * - * @treturn bool isGameOver + * @return boolean isGameOver */ int LuaSyncedRead::IsGameOver(lua_State* L) { @@ -889,8 +888,8 @@ int LuaSyncedRead::IsGameOver(lua_State* L) * * @function Spring.GetGameFrame * - * @treturn number t1 frameNum % dayFrames - * @treturn number t2 frameNum / dayFrames + * @return number t1 frameNum % dayFrames + * @return number t2 frameNum / dayFrames */ int LuaSyncedRead::GetGameFrame(lua_State* L) { @@ -907,7 +906,7 @@ int LuaSyncedRead::GetGameFrame(lua_State* L) * * @function Spring.GetGameSeconds * - * @treturn number seconds + * @return number seconds */ int LuaSyncedRead::GetGameSeconds(lua_State* L) { @@ -926,7 +925,7 @@ int LuaSyncedRead::GetGameSeconds(lua_State* L) * * @function Spring.GetTidal * - * @treturn number tidalStrength + * @return number tidalStrength */ int LuaSyncedRead::GetTidal(lua_State* L) { @@ -939,7 +938,7 @@ int LuaSyncedRead::GetTidal(lua_State* L) * * @function Spring.GetWind * - * @treturn number windStrength + * @return number windStrength */ int LuaSyncedRead::GetWind(lua_State* L) { @@ -963,12 +962,15 @@ int LuaSyncedRead::GetWind(lua_State* L) * The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) ******************************************************************************/ +/** + * @class RulesParams : table + */ /*** * * @function Spring.GetGameRulesParams * - * @treturn {[string] = number,...} rulesParams map with rules names as key and values as values + * @return RulesParams rulesParams map with rules names as key and values as values */ int LuaSyncedRead::GetGameRulesParams(lua_State* L) { @@ -981,9 +983,9 @@ int LuaSyncedRead::GetGameRulesParams(lua_State* L) * * @function Spring.GetTeamRulesParams * - * @tparam number teamID + * @param teamID integer * - * @treturn {[string] = number,...} rulesParams map with rules names as key and values as values + * @return RulesParams rulesParams map with rules names as key and values as values */ int LuaSyncedRead::GetTeamRulesParams(lua_State* L) { @@ -1007,9 +1009,9 @@ int LuaSyncedRead::GetTeamRulesParams(lua_State* L) * * @function Spring.GetPlayerRulesParams * - * @tparam number playerID + * @param playerID integer * - * @treturn {[string] = number,...} rulesParams map with rules names as key and values as values + * @return RulesParams rulesParams map with rules names as key and values as values */ int LuaSyncedRead::GetPlayerRulesParams(lua_State* L) { @@ -1076,9 +1078,9 @@ static int GetUnitRulesParamLosMask(lua_State* L, const CUnit* unit) * * @function Spring.GetUnitRulesParams * - * @tparam number unitID + * @param unitID integer * - * @treturn {[string] = number,...} rulesParams map with rules names as key and values as values + * @return RulesParams rulesParams map with rules names as key and values as values */ int LuaSyncedRead::GetUnitRulesParams(lua_State* L) { @@ -1094,9 +1096,9 @@ int LuaSyncedRead::GetUnitRulesParams(lua_State* L) * * @function Spring.GetFeatureRulesParams * - * @tparam number featureID + * @param featureID integer * - * @treturn {[string] = number,...} rulesParams map with rules names as key and values as values + * @return RulesParams rulesParams map with rules names as key and values as values */ int LuaSyncedRead::GetFeatureRulesParams(lua_State* L) { @@ -1130,9 +1132,9 @@ int LuaSyncedRead::GetFeatureRulesParams(lua_State* L) * * @function Spring.GetGameRulesParam * - * @tparam number|string ruleRef the rule index or name + * @param ruleRef number|string the rule index or name * - * @treturn nil|number|string value + * @return number?|string value */ int LuaSyncedRead::GetGameRulesParam(lua_State* L) { @@ -1145,10 +1147,10 @@ int LuaSyncedRead::GetGameRulesParam(lua_State* L) * * @function Spring.GetTeamRulesParam * - * @number teamID - * @tparam number|string ruleRef the rule index or name + * @param teamID integer + * @param ruleRef number|string the rule index or name * - * @treturn nil|number|string value + * @return nil|number|string value */ int LuaSyncedRead::GetTeamRulesParam(lua_State* L) { @@ -1173,10 +1175,10 @@ int LuaSyncedRead::GetTeamRulesParam(lua_State* L) * * @function Spring.GetPlayerRulesParam * - * @number playerID - * @tparam number|string ruleRef the rule index or name + * @param playerID integer + * @param ruleRef number|string the rule index or name * - * @treturn nil|number|string value + * @return nil|number|string value */ int LuaSyncedRead::GetPlayerRulesParam(lua_State* L) { @@ -1204,10 +1206,10 @@ int LuaSyncedRead::GetPlayerRulesParam(lua_State* L) * * @function Spring.GetUnitRulesParam * - * @number unitID - * @tparam number|string ruleRef the rule index or name + * @param unitID integer + * @param ruleRef number|string the rule index or name * - * @treturn nil|number|string value + * @return nil|number|string value */ int LuaSyncedRead::GetUnitRulesParam(lua_State* L) { @@ -1223,10 +1225,10 @@ int LuaSyncedRead::GetUnitRulesParam(lua_State* L) * * @function Spring.GetFeatureRulesParam * - * @number featureID - * @tparam number|string ruleRef the rule index or name + * @param featureID integer + * @param ruleRef number|string the rule index or name * - * @treturn nil|number|string value + * @return nil|number|string value */ int LuaSyncedRead::GetFeatureRulesParam(lua_State* L) { @@ -1299,9 +1301,9 @@ static int PushAllOptions(lua_State* L, const auto &options) * * @function Spring.GetMapOption * - * @string mapOption + * @param mapOption string * - * @treturn string value of mapOption + * @return string value of mapOption * */ int LuaSyncedRead::GetMapOption(lua_State* L) { @@ -1311,7 +1313,7 @@ int LuaSyncedRead::GetMapOption(lua_State* L) * * @function Spring.GetMapOptions * - * @treturn {[string] = string,...} options map with options names as keys and values as values + * @return [string] = string[] options map with options names as keys and values as values */ int LuaSyncedRead::GetMapOptions(lua_State* L) { @@ -1323,9 +1325,9 @@ int LuaSyncedRead::GetMapOptions(lua_State* L) * * @function Spring.GetModOption * - * @string modOption + * @param modOption string * - * @treturn string value of modOption in option map + * @return string value of modOption in option map */ int LuaSyncedRead::GetModOption(lua_State* L) { @@ -1337,7 +1339,7 @@ int LuaSyncedRead::GetModOption(lua_State* L) * * @function Spring.GetModOptions * - * @treturn {[string] = string,...} options map with options names as keys and values as values + * @return [string] = string[] options map with options names as keys and values as values */ int LuaSyncedRead::GetModOptions(lua_State* L) { @@ -1356,10 +1358,10 @@ int LuaSyncedRead::GetModOptions(lua_State* L) * * @function Spring.GetHeadingFromVector * - * @number x - * @number z + * @param x number + * @param z number * - * @treturn number heading + * @return number heading */ int LuaSyncedRead::GetHeadingFromVector(lua_State* L) { @@ -1375,10 +1377,10 @@ int LuaSyncedRead::GetHeadingFromVector(lua_State* L) * * @function Spring.GetVectorFromHeading * - * @number heading + * @param heading number * - * @treturn number x - * @treturn number z + * @return number x + * @return number z */ int LuaSyncedRead::GetVectorFromHeading(lua_State* L) { @@ -1391,8 +1393,8 @@ int LuaSyncedRead::GetVectorFromHeading(lua_State* L) /*** * @function Spring.GetFacingFromHeading - * @number heading - * @treturn number facing + * @param heading number + * @return number facing */ int LuaSyncedRead::GetFacingFromHeading(lua_State* L) { @@ -1402,8 +1404,8 @@ int LuaSyncedRead::GetFacingFromHeading(lua_State* L) /*** * @function Spring.GetHeadingFromFacing - * @number facing - * @treturn number heading + * @param facing number + * @return number heading */ int LuaSyncedRead::GetHeadingFromFacing(lua_State* L) { @@ -1421,14 +1423,14 @@ int LuaSyncedRead::GetHeadingFromFacing(lua_State* L) /*** Side spec * - * @table sideSpec + * @class SideSpec * * Used when returning arrays of side specifications, is itself an array with * positional values as below: * - * @string sideName - * @string caseName - * @string startUnit + * @field sideName string + * @field caseName string + * @field startUnit string */ @@ -1436,28 +1438,28 @@ int LuaSyncedRead::GetHeadingFromFacing(lua_State* L) * * @function Spring.GetSideData * - * @string sideName + * @param sideName string * - * @treturn nil|string startUnit - * @treturn string caseSensitiveSideName + * @return nil|string startUnit + * @return string caseSensitiveSideName */ /*** * * @function Spring.GetSideData * - * @number sideID + * @param sideID integer * - * @treturn nil|string sideName - * @treturn string startUnit - * @treturn string caseSensitiveSideName + * @return nil|string sideName + * @return string startUnit + * @return string caseSensitiveSideName */ /*** * * @function Spring.GetSideData * - * @treturn {[sideSpec],...} sideArray + * @return SideSpec[] sideArray */ int LuaSyncedRead::GetSideData(lua_State* L) { @@ -1509,7 +1511,7 @@ int LuaSyncedRead::GetSideData(lua_State* L) * * @function Spring.GetGaiaTeamID * - * @treturn number teamID + * @return number teamID */ int LuaSyncedRead::GetGaiaTeamID(lua_State* L) { @@ -1525,12 +1527,12 @@ int LuaSyncedRead::GetGaiaTeamID(lua_State* L) * * @function Spring.GetAllyTeamStartBox * - * @number allyID + * @param allyID integer * - * @treturn[opt] number xMin - * @treturn[opt] number zMin - * @treturn[opt] number xMax - * @treturn[opt] number zMax + * @return number? xMin + * @return number? zMin + * @return number? xMax + * @return number? zMax */ int LuaSyncedRead::GetAllyTeamStartBox(lua_State* L) { @@ -1557,11 +1559,11 @@ int LuaSyncedRead::GetAllyTeamStartBox(lua_State* L) * * @function Spring.GetTeamStartPosition * - * @number teamID + * @param teamID integer * - * @treturn[opt] number x - * @treturn[opt] number y - * @treturn[opt] number x + * @return number? x + * @return number? y + * @return number? x */ int LuaSyncedRead::GetTeamStartPosition(lua_State* L) { @@ -1581,19 +1583,10 @@ int LuaSyncedRead::GetTeamStartPosition(lua_State* L) return 4; } - -/*** Cartesian triple (XYZ) - * @table xyz - * @number x - * @number y - * @number z - */ - - /*** * * @function Spring.GetMapStartPositions - * @treturn {xyz,...} array of positions indexed by teamID + * @return float3[] array of positions indexed by teamID */ int LuaSyncedRead::GetMapStartPositions(lua_State* L) { @@ -1619,7 +1612,7 @@ int LuaSyncedRead::GetMapStartPositions(lua_State* L) /*** * * @function Spring.GetAllyTeamList - * @treturn {number,...} list of allyTeamIDs + * @return number[] list of allyTeamIDs */ int LuaSyncedRead::GetAllyTeamList(lua_State* L) { @@ -1639,8 +1632,8 @@ int LuaSyncedRead::GetAllyTeamList(lua_State* L) /*** * * @function Spring.GetTeamList - * @number[opt=-1] allyTeamID to filter teams belonging to when >= 0 - * @treturn nil|{number,...} list of teamIDs + * @param allyTeamID integer? (Default: -1) to filter teams belonging to when >= 0 + * @return number[]? list of teamIDs */ int LuaSyncedRead::GetTeamList(lua_State* L) { @@ -1680,9 +1673,9 @@ int LuaSyncedRead::GetTeamList(lua_State* L) /*** * * @function Spring.GetPlayerList - * @number[opt=-1] teamID to filter by when >= 0 - * @bool[opt=false] active whether to filter only active teams - * @treturn nil|{number,...} list of playerIDs + * @param teamID integer? (Default: -1) to filter by when >= 0 + * @param active boolean? (Default: false) whether to filter only active teams + * @return number[]? list of playerIDs */ int LuaSyncedRead::GetPlayerList(lua_State* L) { @@ -1734,16 +1727,16 @@ int LuaSyncedRead::GetPlayerList(lua_State* L) /*** * * @function Spring.GetTeamInfo - * @number teamID - * @bool[opt=true] getTeamKeys whether to return the customTeamKeys table - * @treturn nil|number teamID - * @treturn number leader - * @treturn number isDead - * @treturn number hasAI - * @treturn string side - * @treturn number allyTeam - * @treturn number incomeMultiplier - * @treturn {[string]=string,...} customTeamKeys when getTeamKeys is true, otherwise nil + * @param teamID integer + * @param getTeamKeys boolean? (Default: true) whether to return the customTeamKeys table + * @return number? teamID + * @return number leader + * @return number isDead + * @return number hasAI + * @return string side + * @return number allyTeam + * @return number incomeMultiplier + * @return table customTeamKeys when getTeamKeys is true, otherwise nil */ int LuaSyncedRead::GetTeamInfo(lua_State* L) { @@ -1785,8 +1778,8 @@ int LuaSyncedRead::GetTeamInfo(lua_State* L) /*** * * @function Spring.GetTeamAllyTeamID - * @number teamID - * @treturn nil|allyTeamID + * @param teamID integer + * @return integer? allyTeamID */ int LuaSyncedRead::GetTeamAllyTeamID(lua_State* L) { @@ -1806,16 +1799,17 @@ int LuaSyncedRead::GetTeamAllyTeamID(lua_State* L) /*** * * @function Spring.GetTeamResources - * @number teamID - * @string resource one of "m(etal)?|e(nergy)?" - * @treturn nil|number currentLevel - * @treturn number storage - * @treturn number pull - * @treturn number income - * @treturn number expense - * @treturn number share - * @treturn number sent - * @treturn number received + * @param teamID integer + * @param resource ResourceName + * @return number? currentLevel + * @return number storage + * @return number pull + * @return number income + * @return number expense + * @return number share + * @return number sent + * @return number received + * @return number excess */ int LuaSyncedRead::GetTeamResources(lua_State* L) { @@ -1864,13 +1858,13 @@ int LuaSyncedRead::GetTeamResources(lua_State* L) /*** * * @function Spring.GetTeamUnitStats - * @number teamID - * @treturn nil|number killed - * @treturn number died - * @treturn number capturedBy - * @treturn number capturedFrom - * @treturn number received - * @treturn number sent + * @param teamID integer + * @return number? killed + * @return number died + * @return number capturedBy + * @return number capturedFrom + * @return number received + * @return number sent */ int LuaSyncedRead::GetTeamUnitStats(lua_State* L) { @@ -1899,13 +1893,13 @@ int LuaSyncedRead::GetTeamUnitStats(lua_State* L) /*** * * @function Spring.GetTeamResourceStats - * @number teamID - * @string resource one of "m(etal)?|e(nergy)?" - * @treturn nil|number used - * @treturn number produced - * @treturn number excessed - * @treturn number received - * @treturn number sent + * @param teamID integer + * @param resource ResourceName + * @return number? used + * @return number produced + * @return number excessed + * @return number received + * @return number sent */ int LuaSyncedRead::GetTeamResourceStats(lua_State* L) { @@ -1952,9 +1946,9 @@ int LuaSyncedRead::GetTeamResourceStats(lua_State* L) * Returns a team's damage stats. Note that all damage is counted, * including self-inflicted and unconfirmed out-of-sight. * - * @number teamID - * @treturn number damageDealt - * @treturn number damageReceived + * @param teamID integer + * @return number damageDealt + * @return number damageReceived */ int LuaSyncedRead::GetTeamDamageStats(lua_State* L) { @@ -1976,37 +1970,43 @@ int LuaSyncedRead::GetTeamDamageStats(lua_State* L) } -/*** @table teamStats - * @number time - * @number frame - * @number metalUsed - * @number metalProduced - * @number metalExcess - * @number metalReceived - * @number metalSent - * @number energyUsed - * @number energyProduced - * @number energyExcess - * @number energyReceived - * @number energySent - * @number damageDealt - * @number damageReceived - * @number unitsProduced - * @number unitsDied - * @number unitsReceived - * @number unitsSent - * @number unitsCaptured - * @number unitsOutCaptured +/*** + * @class TeamStats + * @field time number + * @field frame number + * @field metalUsed number + * @field metalProduced number + * @field metalExcess number + * @field metalReceived number + * @field metalSent number + * @field energyUsed number + * @field energyProduced number + * @field energyExcess number + * @field energyReceived number + * @field energySent number + * @field damageDealt number + * @field damageReceived number + * @field unitsProduced integer + * @field unitsDied integer + * @field unitsReceived integer + * @field unitsSent integer + * @field unitsCaptured integer + * @field unitsOutCaptured integer */ - /*** - * + * Get the number of history entries. * @function Spring.GetTeamStatsHistory - * @number teamID - * @number[opt] startIndex when not specified return the number of history entries - * @number[opt=startIndex] endIndex - * @treturn nil|number|{teamStats,...} + * @param teamID integer + * @return integer? historyCount The number of history entries, or `nil` if unable to resolve team. + */ +/*** + * Get team stats history. + * @function Spring.GetTeamStatsHistory + * @param teamID integer + * @param startIndex integer + * @param endIndex integer? (Default: startIndex) + * @return TeamStats[] The team stats history, or `nil` if unable to resolve team. */ int LuaSyncedRead::GetTeamStatsHistory(lua_State* L) { @@ -2096,8 +2096,8 @@ int LuaSyncedRead::GetTeamStatsHistory(lua_State* L) /*** * * @function Spring.GetTeamLuaAI - * @number teamID - * @treturn string + * @param teamID integer + * @return string */ int LuaSyncedRead::GetTeamLuaAI(lua_State* L) { @@ -2131,9 +2131,9 @@ int LuaSyncedRead::GetTeamLuaAI(lua_State* L) * Also returns the current unit count for readable teams as the 2nd value. * * @function Spring.GetTeamMaxUnits - * @number teamID - * @treturn number maxUnits - * @treturn nil|number currentUnits + * @param teamID integer + * @return number maxUnits + * @return number? currentUnits */ int LuaSyncedRead::GetTeamMaxUnits(lua_State* L) { @@ -2154,20 +2154,20 @@ int LuaSyncedRead::GetTeamMaxUnits(lua_State* L) /*** * * @function Spring.GetPlayerInfo - * @number playerID - * @bool[opt=true] getPlayerOpts whether to return custom player options - * @treturn nil|string name - * @treturn bool active - * @treturn bool spectator - * @treturn number teamID - * @treturn number allyTeamID - * @treturn number pingTime - * @treturn number cpuUsage - * @treturn string country - * @treturn number rank - * @treturn bool hasSkirmishAIsInTeam - * @treturn {[string]=string} playerOpts when playerOpts is true - * @treturn bool desynced + * @param playerID integer + * @param getPlayerOpts boolean? (Default: true) whether to return custom player options + * @return string name + * @return boolean active + * @return boolean spectator + * @return number teamID + * @return number allyTeamID + * @return number pingTime + * @return number cpuUsage + * @return string country + * @return number rank + * @return boolean hasSkirmishAIsInTeam + * @return {[string]: string} playerOpts when playerOpts is true + * @return boolean desynced */ int LuaSyncedRead::GetPlayerInfo(lua_State* L) { @@ -2219,8 +2219,8 @@ int LuaSyncedRead::GetPlayerInfo(lua_State* L) /*** Returns unit controlled by player on FPS mode * * @function Spring.GetPlayerControlledUnit - * @number playerID - * @treturn nil|number + * @param playerID integer + * @return number? */ int LuaSyncedRead::GetPlayerControlledUnit(lua_State* L) { @@ -2255,13 +2255,13 @@ int LuaSyncedRead::GetPlayerControlledUnit(lua_State* L) /*** * * @function Spring.GetAIInfo - * @number teamID - * @treturn number skirmishAIID - * @treturn string name - * @treturn number hostingPlayerID - * @treturn string shortName when synced "SYNCED_NOSHORTNAME", otherwise the AI shortname or "UNKNOWN" - * @treturn string version when synced "SYNCED_NOVERSION", otherwise the AI version or "UNKNOWN" - * @treturn {[string]=string,...} options + * @param teamID integer + * @return number skirmishAIID + * @return string name + * @return number hostingPlayerID + * @return string shortName when synced "SYNCED_NOSHORTNAME", otherwise the AI shortname or "UNKNOWN" + * @return string version when synced "SYNCED_NOVERSION", otherwise the AI version or "UNKNOWN" + * @return table options */ int LuaSyncedRead::GetAIInfo(lua_State* L) { @@ -2314,8 +2314,8 @@ int LuaSyncedRead::GetAIInfo(lua_State* L) /*** * * @function Spring.GetAllyTeamInfo - * @number allyTeamID - * @treturn nil|{[string]=string,...} + * @param allyTeamID integer + * @return nil|table */ int LuaSyncedRead::GetAllyTeamInfo(lua_State* L) { @@ -2340,9 +2340,9 @@ int LuaSyncedRead::GetAllyTeamInfo(lua_State* L) /*** * * @function Spring.AreTeamsAllied - * @number teamID1 - * @number teamID2 - * @treturn nil|bool + * @param teamID1 number + * @param teamID2 number + * @return nil|boolean */ int LuaSyncedRead::AreTeamsAllied(lua_State* L) { @@ -2360,9 +2360,9 @@ int LuaSyncedRead::AreTeamsAllied(lua_State* L) /*** * * @function Spring.ArePlayersAllied - * @number playerID1 - * @number playerID2 - * @treturn nil|bool + * @param playerID1 number + * @param playerID2 number + * @return nil|boolean */ int LuaSyncedRead::ArePlayersAllied(lua_State* L) { @@ -2405,7 +2405,7 @@ int LuaSyncedRead::ArePlayersAllied(lua_State* L) * * @see UnsyncedRead.GetVisibleUnits * - * @treturn {number,...} unitIDs + * @return number[] unitIDs */ int LuaSyncedRead::GetAllUnits(lua_State* L) { @@ -2434,8 +2434,8 @@ int LuaSyncedRead::GetAllUnits(lua_State* L) /*** * * @function Spring.GetTeamUnits - * @number teamID - * @treturn nil|{number,...} unitIDs + * @param teamID integer + * @return number[]? unitIDs */ int LuaSyncedRead::GetTeamUnits(lua_State* L) { @@ -2534,8 +2534,8 @@ static inline void InsertSearchUnitDefs(const UnitDef* ud, bool allied) /*** * * @function Spring.GetTeamUnitsSorted - * @number teamID - * @treturn nil|{[number]={number,...}} where keys are unitDefIDs and values are unitIDs + * @param teamID integer + * @return table unitsByDef A table where keys are unitDefIDs and values are unitIDs */ int LuaSyncedRead::GetTeamUnitsSorted(lua_State* L) { @@ -2630,8 +2630,8 @@ int LuaSyncedRead::GetTeamUnitsSorted(lua_State* L) /*** * * @function Spring.GetTeamUnitsCounts - * @number teamID - * @treturn nil|{[number]=number} where keys are unitDefIDs and values are counts + * @param teamID integer + * @return table? countByUnit A table where keys are unitDefIDs and values are counts. */ int LuaSyncedRead::GetTeamUnitsCounts(lua_State* L) { @@ -2713,9 +2713,9 @@ int LuaSyncedRead::GetTeamUnitsCounts(lua_State* L) /*** * * @function Spring.GetTeamUnitsByDefs - * @number teamID - * @tparam number|{number,...} unitDefIDs - * @treturn nil|{number,...} unitIDs + * @param teamID integer + * @param unitDefIDs number|number[] + * @return number[]? unitIDs */ int LuaSyncedRead::GetTeamUnitsByDefs(lua_State* L) { @@ -2789,9 +2789,9 @@ int LuaSyncedRead::GetTeamUnitsByDefs(lua_State* L) /*** * * @function Spring.GetTeamUnitDefCount - * @number teamID - * @number unitDefID - * @treturn nil|number count + * @param teamID integer + * @param unitDefID integer + * @return number? count */ int LuaSyncedRead::GetTeamUnitDefCount(lua_State* L) { @@ -2850,8 +2850,8 @@ int LuaSyncedRead::GetTeamUnitDefCount(lua_State* L) /*** * * @function Spring.GetTeamUnitCount - * @number teamID - * @treturn nil|number count + * @param teamID integer + * @return number? count */ int LuaSyncedRead::GetTeamUnitCount(lua_State* L) { @@ -2963,12 +2963,12 @@ void ApplyPlanarTeamError(lua_State* L, int allegiance, float3& mins, float3& ma /*** * * @function Spring.GetUnitsInRectangle - * @number xmin - * @number zmin - * @number xmax - * @number zmax - * @number[opt] allegiance - * @treturn {number,...} unitIDs + * @param xmin number + * @param zmin number + * @param xmax number + * @param zmax number + * @param allegiance number? + * @return number[] unitIDs */ int LuaSyncedRead::GetUnitsInRectangle(lua_State* L) { @@ -3029,14 +3029,14 @@ int LuaSyncedRead::GetUnitsInRectangle(lua_State* L) /*** * * @function Spring.GetUnitsInBox - * @number xmin - * @number ymin - * @number zmin - * @number xmax - * @number ymax - * @number zmax - * @number[opt] allegiance - * @treturn {number,...} unitIDs + * @param xmin number + * @param ymin number + * @param zmin number + * @param xmax number + * @param ymax number + * @param zmax number + * @param allegiance number? + * @return number[] unitIDs */ int LuaSyncedRead::GetUnitsInBox(lua_State* L) { @@ -3099,10 +3099,10 @@ int LuaSyncedRead::GetUnitsInBox(lua_State* L) /*** * * @function Spring.GetUnitsInCylinder - * @number x - * @number z - * @number radius - * @treturn {number,...} unitIDs + * @param x number + * @param z number + * @param radius number + * @return number[] unitIDs */ int LuaSyncedRead::GetUnitsInCylinder(lua_State* L) { @@ -3161,11 +3161,11 @@ int LuaSyncedRead::GetUnitsInCylinder(lua_State* L) /*** * * @function Spring.GetUnitsInSphere - * @number x - * @number y - * @number z - * @number radius - * @treturn {number,...} unitIDs + * @param x number + * @param y number + * @param z number + * @param radius number + * @return number[] unitIDs */ int LuaSyncedRead::GetUnitsInSphere(lua_State* L) { @@ -3241,28 +3241,29 @@ static inline bool UnitInPlanes(const float3& pos, const float radius, const vec return true; } - -/*** @table planeSpec - * @number normalVecX - * @number normalVecY - * @number normalVecZ - * @number d +/*** + * @class Plane + * @field normalVecX number + * @field normalVecY number + * @field normalVecZ number + * @field d number */ - /*** * * @function Spring.GetUnitsInPlanes * * Plane normals point towards accepted space, so the acceptance criteria for each plane is: * - * radius = unit radius - * px, py, pz = unit position - * [(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0 + * ``` + * radius = unit radius + * px, py, pz = unit position + * [(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0 + * ``` * - * @tparam {planeSpec,...} planes - * @number[opt] allegiance - * @treturn nil|{number,...} unitIDs + * @param planes Plane[] + * @param allegiance integer? + * @return integer[] unitIDs */ int LuaSyncedRead::GetUnitsInPlanes(lua_State* L) { @@ -3387,10 +3388,10 @@ static int GetUnitTableCentroid(lua_State *const L, const int indexWithinTable, * Returns nil for an empty array * * @function Spring.GetUnitArrayCentroid - * @tparam table units { unitID, unitID, ... } - * @treturn number centerX - * @treturn number centerY - * @treturn number centerZ + * @param units table { unitID, unitID, ... } + * @return number centerX + * @return number centerY + * @return number centerZ */ int LuaSyncedRead::GetUnitArrayCentroid(lua_State* L) { @@ -3402,10 +3403,10 @@ int LuaSyncedRead::GetUnitArrayCentroid(lua_State* L) * Returns nil for an empty map * * @function Spring.GetUnitMapCentroid - * @tparam table units { [unitID] = true, [unitID] = true, ... } - * @treturn number centerX - * @treturn number centerY - * @treturn number centerZ + * @param units table { [unitID] = true, [unitID] = true, ... } + * @return number centerX + * @return number centerY + * @return number centerZ */ int LuaSyncedRead::GetUnitMapCentroid(lua_State* L) { @@ -3416,9 +3417,9 @@ int LuaSyncedRead::GetUnitMapCentroid(lua_State* L) /*** * * @function Spring.GetUnitNearestAlly - * @number unitID - * @number[opt=1.0e9f] range - * @treturn nil|number unitID + * @param unitID integer + * @param range number? (Default: 1.0e9f) + * @return number? unitID */ int LuaSyncedRead::GetUnitNearestAlly(lua_State* L) { @@ -3441,10 +3442,10 @@ int LuaSyncedRead::GetUnitNearestAlly(lua_State* L) /*** * * @function Spring.GetUnitNearestEnemy - * @number unitID - * @number[opt=1.0e9f] range - * @bool[opt=true] useLOS - * @treturn nil|number unitID + * @param unitID integer + * @param range number? (Default: 1.0e9f) + * @param useLOS boolean? (Default: true) + * @return number? unitID */ int LuaSyncedRead::GetUnitNearestEnemy(lua_State* L) { @@ -3512,11 +3513,11 @@ inline void ProcessFeatures(lua_State* L, const vector& features) { /*** * * @function Spring.GetFeaturesInRectangle - * @number xmin - * @number zmin - * @number xmax - * @number zmax - * @treturn {number,...} featureIDs + * @param xmin number + * @param zmin number + * @param xmax number + * @param zmax number + * @return number[] featureIDs */ int LuaSyncedRead::GetFeaturesInRectangle(lua_State* L) { @@ -3538,11 +3539,11 @@ int LuaSyncedRead::GetFeaturesInRectangle(lua_State* L) /*** * * @function Spring.GetFeaturesInSphere - * @number x - * @number y - * @number z - * @number radius - * @treturn {number,...} featureIDs + * @param x number + * @param y number + * @param z number + * @param radius number + * @return number[] featureIDs */ int LuaSyncedRead::GetFeaturesInSphere(lua_State* L) { @@ -3563,11 +3564,11 @@ int LuaSyncedRead::GetFeaturesInSphere(lua_State* L) /*** * * @function Spring.GetFeaturesInCylinder - * @number x - * @number z - * @number radius - * @number[opt] allegiance - * @treturn {number,...} featureIDs + * @param x number + * @param z number + * @param radius number + * @param allegiance number? + * @return number[] featureIDs */ int LuaSyncedRead::GetFeaturesInCylinder(lua_State* L) { @@ -3587,13 +3588,13 @@ int LuaSyncedRead::GetFeaturesInCylinder(lua_State* L) /*** * * @function Spring.GetProjectilesInRectangle - * @number xmin - * @number zmin - * @number xmax - * @number zmax - * @bool[opt=false] excludeWeaponProjectiles - * @bool[opt=false] excludePieceProjectiles - * @treturn {number,...} projectileIDs + * @param xmin number + * @param zmin number + * @param xmax number + * @param zmax number + * @param excludeWeaponProjectiles boolean? (Default: false) + * @param excludePieceProjectiles boolean? (Default: false) + * @return number[] projectileIDs */ int LuaSyncedRead::GetProjectilesInRectangle(lua_State* L) { @@ -3670,8 +3671,8 @@ int LuaSyncedRead::GetProjectilesInRectangle(lua_State* L) /*** * * @function Spring.ValidUnitID - * @number unitID - * @treturn bool + * @param unitID integer + * @return boolean */ int LuaSyncedRead::ValidUnitID(lua_State* L) { @@ -3680,24 +3681,25 @@ int LuaSyncedRead::ValidUnitID(lua_State* L) } -/*** @table unitState - * @number firestate - * @number movestate - * @bool repeat - * @bool cloak - * @bool active - * @bool trajectory - * @bool autoland optional - * @number autorepairlevel optional - * @bool loopbackattack optional +/*** + * @class UnitState + * @field firestate number + * @field movestate number + * @field repeat boolean + * @field cloak boolean + * @field active boolean + * @field trajectory boolean + * @field autoland boolean? + * @field autorepairlevel number? + * @field loopbackattack boolean? */ /*** * * @function Spring.GetUnitStates - * @number unitID - * @treturn {unitState,...} + * @param unitID integer + * @return UnitState[] */ int LuaSyncedRead::GetUnitStates(lua_State* L) { @@ -3789,9 +3791,9 @@ int LuaSyncedRead::GetUnitStates(lua_State* L) /*** * * @function Spring.GetUnitArmored - * @number unitID - * @treturn nil|bool armored - * @treturn number armorMultiple + * @param unitID integer + * @return nil|boolean armored + * @return number armorMultiple */ int LuaSyncedRead::GetUnitArmored(lua_State* L) { @@ -3808,8 +3810,8 @@ int LuaSyncedRead::GetUnitArmored(lua_State* L) /*** * * @function Spring.GetUnitIsActive - * @number unitID - * @treturn nil|bool + * @param unitID integer + * @return boolean? isActive */ int LuaSyncedRead::GetUnitIsActive(lua_State* L) { @@ -3825,8 +3827,8 @@ int LuaSyncedRead::GetUnitIsActive(lua_State* L) /*** * * @function Spring.GetUnitIsCloaked - * @number unitID - * @treturn nil|bool + * @param unitID integer + * @return boolean? isCloaked */ int LuaSyncedRead::GetUnitIsCloaked(lua_State* L) { @@ -3842,8 +3844,8 @@ int LuaSyncedRead::GetUnitIsCloaked(lua_State* L) /*** * * @function Spring.GetUnitSeismicSignature - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? seismicSignature */ int LuaSyncedRead::GetUnitSeismicSignature(lua_State* L) { @@ -3858,8 +3860,8 @@ int LuaSyncedRead::GetUnitSeismicSignature(lua_State* L) /*** * * @function Spring.GetUnitSelfDTime - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return integer? selfDTime */ int LuaSyncedRead::GetUnitSelfDTime(lua_State* L) { @@ -3875,10 +3877,10 @@ int LuaSyncedRead::GetUnitSelfDTime(lua_State* L) /*** * * @function Spring.GetUnitStockpile - * @number unitID - * @treturn nil|number numStockpiled - * @treturn number numStockpileQued - * @treturn number buildPercent + * @param unitID integer + * @return integer? numStockpiled + * @return integer? numStockpileQued + * @return number? buildPercent */ int LuaSyncedRead::GetUnitStockpile(lua_State* L) { @@ -3899,9 +3901,9 @@ int LuaSyncedRead::GetUnitStockpile(lua_State* L) /*** * * @function Spring.GetUnitSensorRadius - * @number unitID - * @string type one of los, airLos, radar, sonar, seismic, radarJammer, sonarJammer - * @treturn nil|number radius + * @param unitID integer + * @param type string one of los, airLos, radar, sonar, seismic, radarJammer, sonarJammer + * @return number? radius */ int LuaSyncedRead::GetUnitSensorRadius(lua_State* L) { @@ -3942,16 +3944,16 @@ int LuaSyncedRead::GetUnitSensorRadius(lua_State* L) /*** * * @function Spring.GetUnitPosErrorParams - * @number unitID - * @number[opt] allyTeamID - * @treturn nil|number posErrorVectorX - * @treturn number posErrorVectorY - * @treturn number posErrorVectorZ - * @treturn number posErrorDeltaX - * @treturn number posErrorDeltaY - * @treturn number posErrorDeltaZ - * @treturn number nextPosErrorUpdatebaseErrorMult - * @treturn bool posErrorBit + * @param unitID integer + * @param allyTeamID integer? + * @return number? posErrorVectorX + * @return number posErrorVectorY + * @return number posErrorVectorZ + * @return number posErrorDeltaX + * @return number posErrorDeltaY + * @return number posErrorDeltaZ + * @return number nextPosErrorUpdatebaseErrorMult + * @return boolean posErrorBit */ int LuaSyncedRead::GetUnitPosErrorParams(lua_State* L) { @@ -3979,8 +3981,8 @@ int LuaSyncedRead::GetUnitPosErrorParams(lua_State* L) /*** * * @function Spring.GetUnitTooltip - * @number unitID - * @treturn nil|string + * @param unitID integer + * @return nil|string */ int LuaSyncedRead::GetUnitTooltip(lua_State* L) { @@ -4019,8 +4021,8 @@ int LuaSyncedRead::GetUnitTooltip(lua_State* L) /*** * * @function Spring.GetUnitDefID - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? */ int LuaSyncedRead::GetUnitDefID(lua_State* L) { @@ -4044,8 +4046,8 @@ int LuaSyncedRead::GetUnitDefID(lua_State* L) /*** * * @function Spring.GetUnitTeam - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? */ int LuaSyncedRead::GetUnitTeam(lua_State* L) { @@ -4061,8 +4063,8 @@ int LuaSyncedRead::GetUnitTeam(lua_State* L) /*** * * @function Spring.GetUnitAllyTeam - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? */ int LuaSyncedRead::GetUnitAllyTeam(lua_State* L) { @@ -4082,8 +4084,8 @@ int LuaSyncedRead::GetUnitAllyTeam(lua_State* L) * Note that a "neutral" unit can belong to any ally-team (ally, enemy, Gaia). * To check if a unit is Gaia, check its owner team. * - * @number unitID - * @treturn nil|bool + * @param unitID integer + * @return nil|boolean */ int LuaSyncedRead::GetUnitNeutral(lua_State* L) { @@ -4099,12 +4101,12 @@ int LuaSyncedRead::GetUnitNeutral(lua_State* L) /*** * * @function Spring.GetUnitHealth - * @number unitID - * @treturn nil|number health - * @treturn number maxHealth - * @treturn number paralyzeDamage - * @treturn number captureProgress - * @treturn number buildProgress between 0.0-1.0 + * @param unitID integer + * @return number? health + * @return number maxHealth + * @return number paralyzeDamage + * @return number captureProgress + * @return number buildProgress between 0.0-1.0 */ int LuaSyncedRead::GetUnitHealth(lua_State* L) { @@ -4138,8 +4140,8 @@ int LuaSyncedRead::GetUnitHealth(lua_State* L) /*** * * @function Spring.GetUnitIsDead - * @number unitID - * @treturn nil|bool + * @param unitID integer + * @return nil|boolean */ int LuaSyncedRead::GetUnitIsDead(lua_State* L) { @@ -4161,10 +4163,10 @@ int LuaSyncedRead::GetUnitIsDead(lua_State* L) * Use other callouts to differentiate them if you need to. * * @function Spring.GetUnitIsStunned - * @number unitID - * @treturn nil|bool stunnedOrBuilt unit is disabled - * @treturn bool stunned unit is either stunned via EMP or being transported by a non-fireplatform - * @treturn bool beingBuilt unit is under construction + * @param unitID integer + * @return nil|boolean stunnedOrBuilt unit is disabled + * @return boolean stunned unit is either stunned via EMP or being transported by a non-fireplatform + * @return boolean beingBuilt unit is under construction */ int LuaSyncedRead::GetUnitIsStunned(lua_State* L) { @@ -4182,9 +4184,9 @@ int LuaSyncedRead::GetUnitIsStunned(lua_State* L) /*** * * @function Spring.GetUnitIsBeingBuilt - * @number unitID - * @treturn bool beingBuilt - * @treturn number buildProgress + * @param unitID integer + * @return boolean beingBuilt + * @return number buildProgress */ int LuaSyncedRead::GetUnitIsBeingBuilt(lua_State* L) { @@ -4200,11 +4202,11 @@ int LuaSyncedRead::GetUnitIsBeingBuilt(lua_State* L) /*** * * @function Spring.GetUnitResources - * @number unitID - * @treturn nil|number metalMake - * @treturn number metalUse - * @treturn number energyMake - * @treturn number energyUse + * @param unitID integer + * @return number? metalMake + * @return number metalUse + * @return number energyMake + * @return number energyUse */ int LuaSyncedRead::GetUnitResources(lua_State* L) { @@ -4221,9 +4223,9 @@ int LuaSyncedRead::GetUnitResources(lua_State* L) /*** * @function Spring.GetUnitStorage - * @number unitID - * @treturn number Unit's metal storage - * @treturn number Unit's energy storage + * @param unitID integer + * @return number Unit's metal storage + * @return number Unit's energy storage */ int LuaSyncedRead::GetUnitStorage(lua_State* L) { @@ -4239,10 +4241,10 @@ int LuaSyncedRead::GetUnitStorage(lua_State* L) /*** * @function Spring.GetUnitCosts - * @number unitID - * @treturn nil|number buildTime - * @treturn number metalCost - * @treturn number energyCost + * @param unitID integer + * @return number? buildTime + * @return number metalCost + * @return number energyCost */ int LuaSyncedRead::GetUnitCosts(lua_State* L) { @@ -4255,11 +4257,18 @@ int LuaSyncedRead::GetUnitCosts(lua_State* L) lua_pushnumber(L, unit->cost.energy); return 3; } + +/** + * @class ResourceCost + * @field metal number + * @field energy number + */ + /*** * @function Spring.GetUnitCostTable - * @number unitID - * @treturn nil|{ metal = number, energy = number } - * @treturn number buildTime + * @param unitID integer + * @return ResourceCost? cost The cost of the unit, or `nil` if invalid. + * @return number? buildTime The build time the unit, or `nil` if invalid. */ int LuaSyncedRead::GetUnitCostTable(lua_State* L) { @@ -4281,8 +4290,8 @@ int LuaSyncedRead::GetUnitCostTable(lua_State* L) /*** * * @function Spring.GetUnitMetalExtraction - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? metalExtraction */ int LuaSyncedRead::GetUnitMetalExtraction(lua_State* L) { @@ -4301,9 +4310,9 @@ int LuaSyncedRead::GetUnitMetalExtraction(lua_State* L) /*** * * @function Spring.GetUnitExperience - * @number unitID - * @treturn number XP [0.0; +∞) - * @treturn number limXP [0.0; 1.0) as experience approaches infinity + * @param unitID integer + * @return number xp [0.0; +∞) + * @return number limXp [0.0; 1.0) as experience approaches infinity */ int LuaSyncedRead::GetUnitExperience(lua_State* L) { @@ -4320,8 +4329,8 @@ int LuaSyncedRead::GetUnitExperience(lua_State* L) /*** * * @function Spring.GetUnitHeight - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? */ int LuaSyncedRead::GetUnitHeight(lua_State* L) { @@ -4337,8 +4346,8 @@ int LuaSyncedRead::GetUnitHeight(lua_State* L) /*** * * @function Spring.GetUnitRadius - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? */ int LuaSyncedRead::GetUnitRadius(lua_State* L) { @@ -4354,8 +4363,8 @@ int LuaSyncedRead::GetUnitRadius(lua_State* L) * * @function Spring.GetUnitBuildeeRadius * Gets the unit's radius for when targeted by build, repair, reclaim-type commands. - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? */ int LuaSyncedRead::GetUnitBuildeeRadius(lua_State* L) { @@ -4370,8 +4379,8 @@ int LuaSyncedRead::GetUnitBuildeeRadius(lua_State* L) /*** * * @function Spring.GetUnitMass - * @number unitID - * @treturn nil|number + * @param unitID integer + * @return number? */ int LuaSyncedRead::GetUnitMass(lua_State* L) { @@ -4381,18 +4390,18 @@ int LuaSyncedRead::GetUnitMass(lua_State* L) /*** * * @function Spring.GetUnitPosition - * @number unitID - * @bool[opt=false] midPos return midpoint as well - * @bool[opt=false] aimPos return aimpoint as well - * @treturn nil|number basePointX - * @treturn number basePointY - * @treturn number basePointZ - * @treturn nil|number midPointX - * @treturn number midPointY - * @treturn number midPointZ - * @treturn nil|number aimPointX - * @treturn number aimPointY - * @treturn number aimPointZ + * @param unitID integer + * @param midPos boolean? (Default: false) return midpoint as well + * @param aimPos boolean? (Default: false) return aimpoint as well + * @return number? basePointX + * @return number basePointY + * @return number basePointZ + * @return number? midPointX + * @return number midPointY + * @return number midPointZ + * @return number? aimPointX + * @return number aimPointY + * @return number aimPointZ */ int LuaSyncedRead::GetUnitPosition(lua_State* L) { @@ -4402,10 +4411,10 @@ int LuaSyncedRead::GetUnitPosition(lua_State* L) /*** * * @function Spring.GetUnitBasePosition - * @number unitID - * @treturn nil|number posX - * @treturn number posY - * @treturn number posZ + * @param unitID integer + * @return number? posX + * @return number posY + * @return number posZ */ int LuaSyncedRead::GetUnitBasePosition(lua_State* L) { @@ -4416,10 +4425,10 @@ int LuaSyncedRead::GetUnitBasePosition(lua_State* L) /*** * * @function Spring.GetUnitVectors - * @number unitID - * @treturn nil|xyz front - * @treturn xyz up - * @treturn xyz right + * @param unitID integer + * @return float3? front + * @return float3 up + * @return float3 right */ int LuaSyncedRead::GetUnitVectors(lua_State* L) { @@ -4444,10 +4453,10 @@ int LuaSyncedRead::GetUnitVectors(lua_State* L) /*** * * @function Spring.GetUnitRotation - * @number unitID - * @treturn nil|number pitch, rotation in X axis - * @treturn number yaw, rotation in Y axis - * @treturn number roll, rotation in Z axis + * @param unitID integer + * @return number? pitch Rotation in X axis + * @return number? yaw Rotation in Y axis + * @return number? roll Rotation in Z axis */ int LuaSyncedRead::GetUnitRotation(lua_State* L) { @@ -4458,10 +4467,10 @@ int LuaSyncedRead::GetUnitRotation(lua_State* L) /*** * * @function Spring.GetUnitDirection - * @number unitID - * @treturn nil|dirX - * @treturn dirY - * @treturn dirZ + * @param unitID integer + * @return number? dirX + * @return number? dirY + * @return number? dirZ */ int LuaSyncedRead::GetUnitDirection(lua_State* L) { @@ -4480,9 +4489,9 @@ int LuaSyncedRead::GetUnitDirection(lua_State* L) /*** * * @function Spring.GetUnitHeading - * @number unitID - * @bool[opt=false] convertToRadians - * @treturn heading + * @param unitID integer + * @param convertToRadians boolean? (Default: false) + * @return number heading */ int LuaSyncedRead::GetUnitHeading(lua_State* L) { @@ -4503,7 +4512,7 @@ int LuaSyncedRead::GetUnitHeading(lua_State* L) /*** * * @function Spring.GetUnitVelocity - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitVelocity(lua_State* L) { @@ -4514,7 +4523,7 @@ int LuaSyncedRead::GetUnitVelocity(lua_State* L) /*** * * @function Spring.GetUnitBuildFacing - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitBuildFacing(lua_State* L) { @@ -4533,8 +4542,8 @@ int LuaSyncedRead::GetUnitBuildFacing(lua_State* L) * * Works for both mobile builders and factories. * - * @number unitID - * @treturn number buildeeUnitID or nil + * @param unitID integer + * @return number buildeeUnitID or nil */ int LuaSyncedRead::GetUnitIsBuilding(lua_State* L) { @@ -4630,9 +4639,9 @@ static int GetFactoryWorkerTask(lua_State* L, const CFactory *factory) * The possible commands returned are repair, reclaim, resurrect, capture, restore, * and build commands (negative buildee unitDefID). * - * @number unitID - * @treturn number cmdID of the relevant command - * @treturn number targetID if applicable (all except RESTORE) + * @param unitID integer + * @return number cmdID of the relevant command + * @return number targetID if applicable (all except RESTORE) */ int LuaSyncedRead::GetUnitWorkerTask(lua_State* L) { @@ -4653,9 +4662,9 @@ int LuaSyncedRead::GetUnitWorkerTask(lua_State* L) * * @function Spring.GetUnitEffectiveBuildRange * Useful for setting move goals manually. - * @number unitID - * @number buildeeDefID or nil - * @treturn number effectiveBuildRange counted to the center of prospective buildee; buildRange if buildee nil + * @param unitID integer + * @param buildeeDefID integer or nil + * @return number effectiveBuildRange counted to the center of prospective buildee; buildRange if buildee nil */ int LuaSyncedRead::GetUnitEffectiveBuildRange(lua_State* L) { @@ -4708,7 +4717,7 @@ int LuaSyncedRead::GetUnitEffectiveBuildRange(lua_State* L) /*** * * @function Spring.GetUnitCurrentBuildPower - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitCurrentBuildPower(lua_State* L) { @@ -4744,11 +4753,11 @@ int LuaSyncedRead::GetUnitCurrentBuildPower(lua_State* L) * * Checks resources being carried internally by the unit. * - * @number unitID - * @treturn number storedMetal - * @treturn number maxStoredMetal - * @treturn number storedEnergy - * @treturn number maxStoredEnergy + * @param unitID integer + * @return number storedMetal + * @return number maxStoredMetal + * @return number storedEnergy + * @return number maxStoredEnergy */ int LuaSyncedRead::GetUnitHarvestStorage(lua_State* L) { @@ -4766,7 +4775,7 @@ int LuaSyncedRead::GetUnitHarvestStorage(lua_State* L) /*** * * @function Spring.GetUnitBuildParams - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitBuildParams(lua_State* L) { @@ -4803,8 +4812,8 @@ int LuaSyncedRead::GetUnitBuildParams(lua_State* L) * Checks if a builder is in build stance, i.e. can create nanoframes. * Returns nil for non-builders. * - * @number unitID - * @treturn bool inBuildStance + * @param unitID integer + * @return boolean inBuildStance */ int LuaSyncedRead::GetUnitInBuildStance(lua_State* L) { @@ -4833,8 +4842,8 @@ int LuaSyncedRead::GetUnitInBuildStance(lua_State* L) * Only works on builders and factories, returns nil (NOT empty table) * for other units. * - * @number unitID - * @return pieceArray {pieceID, pieceID, ...} + * @param unitID integer + * @return integer[] pieceArray */ int LuaSyncedRead::GetUnitNanoPieces(lua_State* L) { @@ -4884,8 +4893,8 @@ int LuaSyncedRead::GetUnitNanoPieces(lua_State* L) * Returns the unit ID of the transport, if any. * Returns nil if the unit is not being transported. * - * @number unitID - * @treturn number|nil transportUnitID + * @param unitID integer + * @return number|nil transportUnitID */ int LuaSyncedRead::GetUnitTransporter(lua_State* L) { @@ -4901,15 +4910,13 @@ int LuaSyncedRead::GetUnitTransporter(lua_State* L) } -/*** Get units being transported +/*** + * Get units being transported * * @function Spring.GetUnitIsTransporting - * - * Returns an array of unitIDs being transported by this unit. - * Returns nil (NOT an empty array) for units that are not transports. - * - * @number unitID - * @return transporteeArray {unitID, unitID, ...} + * @param unitID integer + * @return integer[]? transporteeArray + * An array of unitIDs being transported by this unit, or `nil` if not a transport. */ int LuaSyncedRead::GetUnitIsTransporting(lua_State* L) { @@ -4935,10 +4942,10 @@ int LuaSyncedRead::GetUnitIsTransporting(lua_State* L) /*** * * @function Spring.GetUnitShieldState - * @number unitID - * @number[opt] weaponNum Optional if the unit has just one shield - * @treturn number isEnabled Warning, number not bool. 0 or 1 - * @treturn number currentPower + * @param unitID integer + * @param weaponNum number? Optional if the unit has just one shield + * @return number isEnabled Warning, number not boolean. 0 or 1 + * @return number currentPower */ int LuaSyncedRead::GetUnitShieldState(lua_State* L) { @@ -4967,7 +4974,7 @@ int LuaSyncedRead::GetUnitShieldState(lua_State* L) /*** * * @function Spring.GetUnitFlanking - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitFlanking(lua_State* L) { @@ -5031,8 +5038,8 @@ int LuaSyncedRead::GetUnitFlanking(lua_State* L) * By default this is the highest among the unit's weapon ranges (hence name), * but can be changed dynamically. Also note that unarmed units ignore this. * - * @number unitID - * @treturn number maxRange + * @param unitID integer + * @return number maxRange */ int LuaSyncedRead::GetUnitMaxRange(lua_State* L) { @@ -5078,9 +5085,9 @@ int LuaSyncedRead::GetUnitMaxRange(lua_State* L) * The state "salvoError" is an exception and returns a table: {x, y, z}, * which represents the inaccuracy error of the ongoing burst. * - * @number unitID - * @number weaponNum - * @string stateName + * @param unitID integer + * @param weaponNum number + * @param stateName string * @return number stateValue */ int LuaSyncedRead::GetUnitWeaponState(lua_State* L) @@ -5261,7 +5268,7 @@ static inline int PushDamagesKey(lua_State* L, const DynDamageArray& damages, in /*** * * @function Spring.GetUnitWeaponDamages - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitWeaponDamages(lua_State* L) { @@ -5300,7 +5307,7 @@ int LuaSyncedRead::GetUnitWeaponDamages(lua_State* L) /*** * * @function Spring.GetUnitWeaponVectors - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitWeaponVectors(lua_State* L) { @@ -5340,7 +5347,7 @@ int LuaSyncedRead::GetUnitWeaponVectors(lua_State* L) /*** * * @function Spring.GetUnitWeaponTryTarget - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitWeaponTryTarget(lua_State* L) { @@ -5385,7 +5392,7 @@ int LuaSyncedRead::GetUnitWeaponTryTarget(lua_State* L) /*** * * @function Spring.GetUnitWeaponTestTarget - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitWeaponTestTarget(lua_State* L) { @@ -5423,7 +5430,7 @@ int LuaSyncedRead::GetUnitWeaponTestTarget(lua_State* L) /*** * * @function Spring.GetUnitWeaponTestRange - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitWeaponTestRange(lua_State* L) { @@ -5461,7 +5468,7 @@ int LuaSyncedRead::GetUnitWeaponTestRange(lua_State* L) /*** * * @function Spring.GetUnitWeaponHaveFreeLineOfFire - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitWeaponHaveFreeLineOfFire(lua_State* L) { @@ -5527,7 +5534,7 @@ int LuaSyncedRead::GetUnitWeaponHaveFreeLineOfFire(lua_State* L) /*** * * @function Spring.GetUnitWeaponCanFire - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitWeaponCanFire(lua_State* L) { @@ -5549,15 +5556,64 @@ int LuaSyncedRead::GetUnitWeaponCanFire(lua_State* L) return 1; } -/*** Checks a weapon's target +/*** + * @alias TargetType + * | 0 # none + * | 1 # unit + * | 2 # position + * | 3 # projectile + */ + +/*** + * Checks a weapon's target + * + * Note that this doesn't need to reflect the unit's Attack orders or such, and + * that weapons can aim individually unless slaved. + * + * @function Spring.GetUnitWeaponTarget + * @param unitID integer + * @param weaponNum integer + * @return 0 TargetType none + * @return boolean isUserTarget + */ +/*** + * Checks a weapon's target + * + * Note that this doesn't need to reflect the unit's Attack orders or such, and + * that weapons can aim individually unless slaved. + * + * @function Spring.GetUnitWeaponTarget + * @param unitID integer + * @param weaponNum integer + * @return 1 TargetType unit + * @return boolean isUserTarget + * @return integer targetUnitID + */ +/*** + * Checks a weapon's target + * + * Note that this doesn't need to reflect the unit's Attack orders or such, and + * that weapons can aim individually unless slaved. + * + * @function Spring.GetUnitWeaponTarget + * @param unitID integer + * @param weaponNum integer + * @return 2 TargetType position + * @return boolean isUserTarget + * @return float3 targetPosition + */ +/*** + * Checks a weapon's target + * + * Note that this doesn't need to reflect the unit's Attack orders or such, and + * that weapons can aim individually unless slaved. * - * Note that this doesn't need to reflect the unit's Attack orders or such, and that weapons can aim individually unless slaved. * @function Spring.GetUnitWeaponTarget - * @number unitID - * @number weaponNum - * @treturn number targetType (0: none, 1: unit, 2: position, 3: projectile) - * @treturn boolean isUserTarget - * @return target (depending on type, 0: nil, 1: unitID, 2: table {x, y, z}, 3: projectileID) + * @param unitID integer + * @param weaponNum integer + * @return 3 TargetType projectileID + * @return boolean isUserTarget + * @return integer targetProjectileId */ int LuaSyncedRead::GetUnitWeaponTarget(lua_State* L) { @@ -5618,7 +5674,7 @@ int LuaSyncedRead::GetUnitFuel(lua_State* L) { lua_pushnumber(L, 0.0f); return 1 /*** * * @function Spring.GetUnitEstimatedPath - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitEstimatedPath(lua_State* L) { @@ -5638,7 +5694,7 @@ int LuaSyncedRead::GetUnitEstimatedPath(lua_State* L) /*** * * @function Spring.GetUnitLastAttacker - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitLastAttacker(lua_State* L) { @@ -5658,7 +5714,7 @@ int LuaSyncedRead::GetUnitLastAttacker(lua_State* L) /*** * * @function Spring.GetUnitLastAttackedPiece - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitLastAttackedPiece(lua_State* L) { @@ -5668,7 +5724,7 @@ int LuaSyncedRead::GetUnitLastAttackedPiece(lua_State* L) /*** * * @function Spring.GetUnitCollisionVolumeData - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitCollisionVolumeData(lua_State* L) { @@ -5689,11 +5745,11 @@ int LuaSyncedRead::GetUnitPieceCollisionVolumeData(lua_State* L) /*** * * @function Spring.GetUnitSeparation - * @number unitID1 - * @number unitID2 - * @bool[opt=false] direction to subtract from, default unitID1 - unitID2 - * @bool[opt=false] subtractRadii whether units radii should be subtracted from the total - * @treturn nil|number + * @param unitID1 number + * @param unitID2 number + * @param direction boolean? (Default: false) to subtract from, default unitID1 - unitID2 + * @param subtractRadii boolean? (Default: false) whether units radii should be subtracted from the total + * @return number? */ int LuaSyncedRead::GetUnitSeparation(lua_State* L) { @@ -5731,7 +5787,7 @@ int LuaSyncedRead::GetUnitSeparation(lua_State* L) /*** * * @function Spring.GetUnitFeatureSeparation - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitFeatureSeparation(lua_State* L) { @@ -5766,7 +5822,7 @@ int LuaSyncedRead::GetUnitFeatureSeparation(lua_State* L) /*** * * @function Spring.GetUnitDefDimensions - * @number unitDefID + * @param unitDefID integer */ int LuaSyncedRead::GetUnitDefDimensions(lua_State* L) { @@ -5811,14 +5867,14 @@ int LuaSyncedRead::GetCEGID(lua_State* L) /*** * * @function Spring.GetUnitBlocking - * @number unitID - * @treturn nil|bool isBlocking - * @treturn bool isSolidObjectCollidable - * @treturn bool isProjectileCollidable - * @treturn bool isRaySegmentCollidable - * @treturn bool crushable - * @treturn bool blockEnemyPushing - * @treturn bool blockHeightChanges + * @param unitID integer + * @return nil|boolean isBlocking + * @return boolean isSolidObjectCollidable + * @return boolean isProjectileCollidable + * @return boolean isRaySegmentCollidable + * @return boolean crushable + * @return boolean blockEnemyPushing + * @return boolean blockHeightChanges */ int LuaSyncedRead::GetUnitBlocking(lua_State* L) { @@ -5829,7 +5885,7 @@ int LuaSyncedRead::GetUnitBlocking(lua_State* L) /*** * * @function Spring.GetUnitMoveTypeData - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitMoveTypeData(lua_State* L) { @@ -6055,8 +6111,8 @@ static void PackCommandQueue(lua_State* L, const CCommandQueue& commands, size_t * * @function Spring.GetUnitCurrentCommand * - * @number unitID Unit id. - * @number cmdIndex Command index to get. If negative will count from the end of the queue, + * @param unitID integer Unit id. + * @param cmdIndex integer Command index to get. If negative will count from the end of the queue, * for example -1 will be the last command. */ int LuaSyncedRead::GetUnitCurrentCommand(lua_State* L) @@ -6093,40 +6149,28 @@ int LuaSyncedRead::GetUnitCurrentCommand(lua_State* L) return 3 + numParams; } - -/*** Parameters for command options - * - * @table cmdOpts +/*** + * Get the commands for a unit. * - * @number coded - * @bool alt - * @bool ctrl - * @bool shift - * @bool right - * @bool meta - * @bool internal - */ - -/*** Command + * @function Spring.GetUnitCommands * - * @table cmd + * Same as `Spring.GetCommandQueue` * - * @number id - * @tparam {number,...} params - * @tparam cmdOpts options - * @number tag + * @param unitID integer + * @param count integer Number of commands to return, `-1` returns all commands, `0` returns command count. + * @return Command[] commands */ - - -/*** Get the number or list of commands for a unit +/** + * Get the count of commands for a unit. * * @function Spring.GetUnitCommands * - * Same as Spring.GetCommandQueue + * Same as `Spring.GetCommandQueue` + * + * @param unitID integer + * @param count 0 Returns the number of commands in the units queue. + * @return integer The number of commands in the unit queue. * - * @number unitID - * @number count when 0 returns the number of commands in the units queue, when -1 returns all commands, number of commands to return otherwise - * @treturn number|{cmd,...} commands */ int LuaSyncedRead::GetUnitCommands(lua_State* L) { @@ -6163,9 +6207,9 @@ int LuaSyncedRead::GetUnitCommands(lua_State* L) * * @function Spring.GetFactoryCommands * - * @number unitID - * @number count when 0 returns the number of commands in the units queue, when -1 returns all commands, number of commands to return otherwise - * @treturn number|{cmd,...} commands + * @param unitID integer + * @param count number when 0 returns the number of commands in the units queue, when -1 returns all commands, number of commands to return otherwise + * @return number|Command[] commands */ int LuaSyncedRead::GetFactoryCommands(lua_State* L) { @@ -6197,7 +6241,7 @@ int LuaSyncedRead::GetFactoryCommands(lua_State* L) /*** Get the number of commands in a units queue. * - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitCommandCount(lua_State* L) { @@ -6219,7 +6263,7 @@ int LuaSyncedRead::GetUnitCommandCount(lua_State* L) /*** * * @function Spring.GetFactoryBuggerOff - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetFactoryBuggerOff(lua_State* L) { @@ -6299,11 +6343,11 @@ static void PackFactoryCounts(lua_State* L, /*** Gets the build queue of a factory * * @function Spring.GetFactoryCounts - * @number unitID - * @number[opt=-1] count then number of commands to retrieve, when -1 all - * @bool[opt=false] addCmds if commands other than buildunit are retrieved + * @param unitID integer + * @param count integer? (Default: -1) Number of commands to retrieve, `-1` for all. + * @param addCmds boolean? (Default: false) Retrieve commands other than buildunit * - * @treturn nil|{{[number]=number,...}} counts indexed by unitDefID or -cmdID + * @return table? counts Build queue count by `unitDefID` or `-cmdID`, or `nil` if unit is not found. */ int LuaSyncedRead::GetFactoryCounts(lua_State* L) { @@ -6332,16 +6376,30 @@ int LuaSyncedRead::GetFactoryCounts(lua_State* L) } -/*** Get the number or list of commands for a unit +/*** + * Get the commands for a unit. + * + * @function Spring.GetCommandQueue + * + * Same as `Spring.GetUnitCommands` + * + * @param unitID integer + * @param count integer Number of commands to return, `-1` returns all commands, `0` returns command count. + * @return Command[] commands + */ +/** + * Get the count of commands for a unit. * * @function Spring.GetCommandQueue * - * Same as Spring.GetUnitCommands + * Same as `Spring.GetUnitCommands` + * + * @param unitID integer + * @param count 0 Returns the number of commands in the units queue. + * @return integer The number of commands in the unit queue. * - * @number unitID - * @number count when 0 returns the number of commands in the units queue, when -1 returns all commands, number of commands to return otherwise - * @treturn number|{cmd,...} commands */ + int LuaSyncedRead::GetCommandQueue(lua_State* L) { return (GetUnitCommands(L)); @@ -6423,8 +6481,8 @@ static int PackBuildQueue(lua_State* L, bool canBuild, const char* caller) /*** Returns the build queue * * @function Spring.GetFullBuildQueue - * @number unitID - * @treturn nil|{[number]=number,...} buildqueue indexed by unitDefID with count values + * @param unitID integer + * @return nil|table buildqueue indexed by unitDefID with count values */ int LuaSyncedRead::GetFullBuildQueue(lua_State* L) { @@ -6435,8 +6493,8 @@ int LuaSyncedRead::GetFullBuildQueue(lua_State* L) /*** Returns the build queue cleaned of things the unit can't build itself * * @function Spring.GetRealBuildQueue - * @number unitID - * @treturn nil|{[number]=number,...} buildqueue indexed by unitDefID with count values + * @param unitID integer + * @return nil|table buildqueue indexed by unitDefID with count values */ int LuaSyncedRead::GetRealBuildQueue(lua_State* L) { @@ -6450,7 +6508,7 @@ int LuaSyncedRead::GetRealBuildQueue(lua_State* L) /*** * * @function Spring.GetUnitCmdDescs - * @number unitID + * @param unitID integer */ int LuaSyncedRead::GetUnitCmdDescs(lua_State* L) { @@ -6489,7 +6547,7 @@ int LuaSyncedRead::GetUnitCmdDescs(lua_State* L) /*** * * @function Spring.FindUnitCmdDesc - * @number unitID + * @param unitID integer */ int LuaSyncedRead::FindUnitCmdDesc(lua_State* L) { @@ -6516,8 +6574,8 @@ int LuaSyncedRead::FindUnitCmdDesc(lua_State* L) /*** * * @function Spring.ValidFeatureID - * @number featureID - * @treturn bool + * @param featureID integer + * @return boolean */ int LuaSyncedRead::ValidFeatureID(lua_State* L) { @@ -6557,8 +6615,8 @@ int LuaSyncedRead::GetAllFeatures(lua_State* L) /*** * * @function Spring.GetFeatureDefID - * @number featureID - * @treturn nil|number + * @param featureID integer + * @return number? */ int LuaSyncedRead::GetFeatureDefID(lua_State* L) { @@ -6574,8 +6632,8 @@ int LuaSyncedRead::GetFeatureDefID(lua_State* L) /*** * * @function Spring.GetFeatureTeam - * @number featureID - * @treturn nil|number + * @param featureID integer + * @return number? */ int LuaSyncedRead::GetFeatureTeam(lua_State* L) { @@ -6595,8 +6653,8 @@ int LuaSyncedRead::GetFeatureTeam(lua_State* L) /*** * * @function Spring.GetFeatureAllyTeam - * @number featureID - * @treturn nil|number + * @param featureID integer + * @return number? */ int LuaSyncedRead::GetFeatureAllyTeam(lua_State* L) { @@ -6612,10 +6670,10 @@ int LuaSyncedRead::GetFeatureAllyTeam(lua_State* L) /*** * * @function Spring.GetFeatureHealth - * @number featureID - * @treturn nil|number health - * @treturn number defHealth - * @treturn number resurrectProgress + * @param featureID integer + * @return number? health + * @return number defHealth + * @return number resurrectProgress */ int LuaSyncedRead::GetFeatureHealth(lua_State* L) { @@ -6633,8 +6691,8 @@ int LuaSyncedRead::GetFeatureHealth(lua_State* L) /*** * * @function Spring.GetFeatureHeight - * @number featureID - * @treturn nil|number + * @param featureID integer + * @return number? */ int LuaSyncedRead::GetFeatureHeight(lua_State* L) { @@ -6650,8 +6708,8 @@ int LuaSyncedRead::GetFeatureHeight(lua_State* L) /*** * * @function Spring.GetFeatureRadius - * @number featureID - * @treturn nil|number + * @param featureID integer + * @return number? */ int LuaSyncedRead::GetFeatureRadius(lua_State* L) { @@ -6666,8 +6724,8 @@ int LuaSyncedRead::GetFeatureRadius(lua_State* L) /*** * * @function Spring.GetFeatureMass - * @number featureID - * @treturn nil|number + * @param featureID integer + * @return number? */ int LuaSyncedRead::GetFeatureMass(lua_State* L) { @@ -6677,7 +6735,7 @@ int LuaSyncedRead::GetFeatureMass(lua_State* L) /*** * * @function Spring.GetFeaturePosition - * @number featureID + * @param featureID integer */ int LuaSyncedRead::GetFeaturePosition(lua_State* L) { @@ -6688,10 +6746,10 @@ int LuaSyncedRead::GetFeaturePosition(lua_State* L) /*** * * @function Spring.GetFeatureSeparation - * @number featureID1 - * @number featureID2 - * @bool[opt=false] direction to subtract from, default featureID1 - featureID2 - * @treturn nil|number + * @param featureID1 number + * @param featureID2 number + * @param direction boolean? (Default: false) to subtract from, default featureID1 - featureID2 + * @return number? */ int LuaSyncedRead::GetFeatureSeparation(lua_State* L) { @@ -6720,10 +6778,10 @@ int LuaSyncedRead::GetFeatureSeparation(lua_State* L) /*** * * @function Spring.GetFeatureRotation - * @number featureID - * @treturn nil|number pitch, rotation in X axis - * @treturn number yaw, rotation in Y axis - * @treturn number roll, rotation in Z axis + * @param featureID integer + * @return number? pitch Rotation in X axis + * @return number? yaw Rotation in Y axis + * @return number? roll Rotation in Z axis */ int LuaSyncedRead::GetFeatureRotation(lua_State* L) { @@ -6737,10 +6795,10 @@ int LuaSyncedRead::GetFeatureRotation(lua_State* L) /*** * * @function Spring.GetFeatureDirection - * @number featureID - * @treturn nil|dirX - * @treturn dirY - * @treturn dirZ + * @param featureID integer + * @return number? dirX + * @return number? dirY + * @return number? dirZ */ int LuaSyncedRead::GetFeatureDirection(lua_State* L) { @@ -6761,7 +6819,7 @@ int LuaSyncedRead::GetFeatureDirection(lua_State* L) /*** * * @function Spring.GetFeatureVelocity - * @number featureID + * @param featureID integer */ int LuaSyncedRead::GetFeatureVelocity(lua_State* L) { @@ -6772,7 +6830,7 @@ int LuaSyncedRead::GetFeatureVelocity(lua_State* L) /*** * * @function Spring.GetFeatureHeading - * @number featureID + * @param featureID integer */ int LuaSyncedRead::GetFeatureHeading(lua_State* L) { @@ -6788,13 +6846,13 @@ int LuaSyncedRead::GetFeatureHeading(lua_State* L) /*** * * @function Spring.GetFeatureResources - * @number featureID - * @treturn nil|number metal - * @treturn number defMetal - * @treturn number energy - * @treturn number defEnergy - * @treturn number reclaimLeft - * @treturn number reclaimTime + * @param featureID integer + * @return number? metal + * @return number defMetal + * @return number energy + * @return number defEnergy + * @return number reclaimLeft + * @return number reclaimTime */ int LuaSyncedRead::GetFeatureResources(lua_State* L) { @@ -6815,14 +6873,14 @@ int LuaSyncedRead::GetFeatureResources(lua_State* L) /*** * * @function Spring.GetFeatureBlocking - * @number featureID - * @treturn nil|bool isBlocking - * @treturn bool isSolidObjectCollidable - * @treturn bool isProjectileCollidable - * @treturn bool isRaySegmentCollidable - * @treturn bool crushable - * @treturn bool blockEnemyPushing - * @treturn bool blockHeightChanges + * @param featureID integer + * @return nil|boolean isBlocking + * @return boolean isSolidObjectCollidable + * @return boolean isProjectileCollidable + * @return boolean isRaySegmentCollidable + * @return boolean crushable + * @return boolean blockEnemyPushing + * @return boolean blockHeightChanges */ int LuaSyncedRead::GetFeatureBlocking(lua_State* L) { @@ -6833,8 +6891,8 @@ int LuaSyncedRead::GetFeatureBlocking(lua_State* L) /*** * * @function Spring.GetFeatureNoSelect - * @number featureID - * @treturn nil|bool + * @param featureID integer + * @return nil|boolean */ int LuaSyncedRead::GetFeatureNoSelect(lua_State* L) { @@ -6851,7 +6909,7 @@ int LuaSyncedRead::GetFeatureNoSelect(lua_State* L) /*** * * @function Spring.GetFeatureResurrect - * @number featureID + * @param featureID integer */ int LuaSyncedRead::GetFeatureResurrect(lua_State* L) { @@ -6874,7 +6932,7 @@ int LuaSyncedRead::GetFeatureResurrect(lua_State* L) /*** * * @function Spring.GetFeatureLastAttackedPiece - * @number featureID + * @param featureID integer */ int LuaSyncedRead::GetFeatureLastAttackedPiece(lua_State* L) { @@ -6884,7 +6942,7 @@ int LuaSyncedRead::GetFeatureLastAttackedPiece(lua_State* L) /*** * * @function Spring.GetFeatureCollisionVolumeData - * @number featureID + * @param featureID integer */ int LuaSyncedRead::GetFeatureCollisionVolumeData(lua_State* L) { @@ -6899,7 +6957,7 @@ int LuaSyncedRead::GetFeatureCollisionVolumeData(lua_State* L) /*** * * @function Spring.GetFeaturePieceCollisionVolumeData - * @number featureID + * @param featureID integer */ int LuaSyncedRead::GetFeaturePieceCollisionVolumeData(lua_State* L) { @@ -6917,10 +6975,10 @@ int LuaSyncedRead::GetFeaturePieceCollisionVolumeData(lua_State* L) /*** * * @function Spring.GetProjectilePosition - * @number projectileID - * @treturn nil|number posX - * @treturn number posY - * @treturn number posZ + * @param projectileID integer + * @return number? posX + * @return number posY + * @return number posZ */ int LuaSyncedRead::GetProjectilePosition(lua_State* L) { @@ -6938,10 +6996,10 @@ int LuaSyncedRead::GetProjectilePosition(lua_State* L) /*** * * @function Spring.GetProjectileDirection - * @number projectileID - * @treturn nil|number dirX - * @treturn number dirY - * @treturn number dirZ + * @param projectileID integer + * @return number? dirX + * @return number dirY + * @return number dirZ */ int LuaSyncedRead::GetProjectileDirection(lua_State* L) { @@ -6959,11 +7017,11 @@ int LuaSyncedRead::GetProjectileDirection(lua_State* L) /*** * * @function Spring.GetProjectileVelocity - * @number projectileID - * @treturn nil|number velX - * @treturn number velY - * @treturn number velZ - * @treturn number velW + * @param projectileID integer + * @return number? velX + * @return number velY + * @return number velZ + * @return number velW */ int LuaSyncedRead::GetProjectileVelocity(lua_State* L) { @@ -6974,8 +7032,8 @@ int LuaSyncedRead::GetProjectileVelocity(lua_State* L) /*** * * @function Spring.GetProjectileGravity - * @number projectileID - * @treturn nil|number + * @param projectileID integer + * @return number? */ int LuaSyncedRead::GetProjectileGravity(lua_State* L) { @@ -6993,13 +7051,13 @@ int LuaSyncedRead::GetProjectileGravity(lua_State* L) /*** * * @function Spring.GetPieceProjectileParams - * @number projectileID - * @treturn nil|number explosionFlags encoded bitwise with SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 - * @treturn number spinAngle - * @treturn number spinSpeed - * @treturn number spinVectorX - * @treturn number spinVectorY - * @treturn number spinVectorZ + * @param projectileID integer + * @return number? explosionFlags encoded bitwise with SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 + * @return number spinAngle + * @return number spinSpeed + * @return number spinVectorX + * @return number spinVectorY + * @return number spinVectorZ */ int LuaSyncedRead::GetPieceProjectileParams(lua_State* L) { @@ -7023,13 +7081,13 @@ int LuaSyncedRead::GetPieceProjectileParams(lua_State* L) /*** * * @function Spring.GetProjectileTarget - * @number projectileID - * @treturn nil|number targetTypeInt where + * @param projectileID integer + * @return number? targetTypeInt where * string.byte('g') := GROUND * string.byte('u') := UNIT * string.byte('f') := FEATURE * string.byte('p') := PROJECTILE - * @treturn number|xyz target targetID or targetPos when targetTypeInt == string.byte('g') + * @return number|float3 target targetID or targetPos when targetTypeInt == string.byte('g') */ int LuaSyncedRead::GetProjectileTarget(lua_State* L) { @@ -7075,8 +7133,8 @@ int LuaSyncedRead::GetProjectileTarget(lua_State* L) /*** * * @function Spring.GetProjectileIsIntercepted - * @number projectileID - * @treturn nil|bool + * @param projectileID integer + * @return nil|boolean */ int LuaSyncedRead::GetProjectileIsIntercepted(lua_State* L) { @@ -7095,8 +7153,8 @@ int LuaSyncedRead::GetProjectileIsIntercepted(lua_State* L) /*** * * @function Spring.GetProjectileTimeToLive - * @number projectileID - * @treturn nil|number + * @param projectileID integer + * @return number? */ int LuaSyncedRead::GetProjectileTimeToLive(lua_State* L) { @@ -7115,8 +7173,8 @@ int LuaSyncedRead::GetProjectileTimeToLive(lua_State* L) /*** * * @function Spring.GetProjectileOwnerID - * @number projectileID - * @treturn nil|number + * @param projectileID integer + * @return number? */ int LuaSyncedRead::GetProjectileOwnerID(lua_State* L) { @@ -7137,8 +7195,8 @@ int LuaSyncedRead::GetProjectileOwnerID(lua_State* L) /*** * * @function Spring.GetProjectileTeamID - * @number projectileID - * @treturn nil|number + * @param projectileID integer + * @return number? */ int LuaSyncedRead::GetProjectileTeamID(lua_State* L) { @@ -7158,8 +7216,8 @@ int LuaSyncedRead::GetProjectileTeamID(lua_State* L) /*** * * @function Spring.GetProjectileAllyTeamID - * @number projectileID - * @treturn nil|number + * @param projectileID integer + * @return number? */ int LuaSyncedRead::GetProjectileAllyTeamID(lua_State* L) { @@ -7179,9 +7237,9 @@ int LuaSyncedRead::GetProjectileAllyTeamID(lua_State* L) /*** * * @function Spring.GetProjectileType - * @number projectileID - * @treturn nil|bool weapon - * @treturn bool piece + * @param projectileID integer + * @return nil|boolean weapon + * @return boolean piece */ int LuaSyncedRead::GetProjectileType(lua_State* L) { @@ -7202,8 +7260,8 @@ int LuaSyncedRead::GetProjectileType(lua_State* L) * * Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName * - * @number projectileID - * @treturn nil|number + * @param projectileID integer + * @return number? */ int LuaSyncedRead::GetProjectileDefID(lua_State* L) { @@ -7228,8 +7286,8 @@ int LuaSyncedRead::GetProjectileDefID(lua_State* L) /*** * * @function Spring.GetProjectileDamages - * @number projectileID - * @string tag one of: + * @param projectileID integer + * @param tag string one of: * "paralyzeDamageTime" * "impulseFactor" * "impulseBoost" @@ -7245,7 +7303,7 @@ int LuaSyncedRead::GetProjectileDefID(lua_State* L) * "explosionSpeed" * - or - * an armor type index to get the damage against it. - * @treturn nil|number + * @return number? */ int LuaSyncedRead::GetProjectileDamages(lua_State* L) { @@ -7276,10 +7334,10 @@ int LuaSyncedRead::GetProjectileDamages(lua_State* L) /*** * * @function Spring.IsPosInMap - * @number x - * @number z - * @treturn boolean inPlayArea whether the position is in the active play area - * @treturn boolean inMap whether the position is in the full map area (currently this is the same as above) + * @param x number + * @param z number + * @return boolean inPlayArea whether the position is in the active play area + * @return boolean inMap whether the position is in the full map area (currently this is the same as above) */ int LuaSyncedRead::IsPosInMap(lua_State* L) { @@ -7319,9 +7377,9 @@ int LuaSyncedRead::IsPosInMap(lua_State* L) * On sea, this returns the negative depth of the seafloor * * @function Spring.GetGroundHeight - * @number x - * @number z - * @treturn number + * @param x number + * @param z number + * @return number */ int LuaSyncedRead::GetGroundHeight(lua_State* L) { @@ -7338,7 +7396,7 @@ int LuaSyncedRead::GetGroundHeight(lua_State* L) * * @see Spring.GetWaterLevel * @function Spring.GetWaterPlaneLevel - * @treturn number waterPlaneLevel + * @return number waterPlaneLevel */ int LuaSyncedRead::GetWaterPlaneLevel(lua_State* L) { @@ -7352,9 +7410,9 @@ int LuaSyncedRead::GetWaterPlaneLevel(lua_State* L) * However water may become more dynamic at some point so by using this you are future-proof. * * @function Spring.GetWaterLevel - * @number x - * @number z - * @treturn number waterLevel + * @param x number + * @param z number + * @return number waterLevel */ int LuaSyncedRead::GetWaterLevel(lua_State* L) { @@ -7370,9 +7428,9 @@ int LuaSyncedRead::GetWaterLevel(lua_State* L) * Returns the original height before the ground got deformed * * @function Spring.GetGroundOrigHeight - * @number x - * @number z - * @treturn number + * @param x number + * @param z number + * @return number */ int LuaSyncedRead::GetGroundOrigHeight(lua_State* L) { @@ -7386,13 +7444,13 @@ int LuaSyncedRead::GetGroundOrigHeight(lua_State* L) /*** * * @function Spring.GetGroundNormal - * @number x - * @number z - * @bool[opt=false] smoothed raw or smoothed center normal - * @treturn number normalX - * @treturn number normalY - * @treturn number normalZ - * @treturn number slope + * @param x number + * @param z number + * @param smoothed boolean? (Default: false) raw or smoothed center normal + * @return number normalX + * @return number normalY + * @return number normalZ + * @return number slope */ int LuaSyncedRead::GetGroundNormal(lua_State* L) { @@ -7416,19 +7474,19 @@ int LuaSyncedRead::GetGroundNormal(lua_State* L) /*** * * @function Spring.GetGroundInfo - * @number x - * @number z - * @treturn number ix - * @treturn number iz - * @treturn number terrainTypeIndex - * @treturn string name - * @treturn number metalExtraction - * @treturn number hardness - * @treturn number tankSpeed - * @treturn number kbotSpeed - * @treturn number hoverSpeed - * @treturn number shipSpeed - * @treturn bool receiveTracks + * @param x number + * @param z number + * @return number ix + * @return number iz + * @return number terrainTypeIndex + * @return string name + * @return number metalExtraction + * @return number hardness + * @return number tankSpeed + * @return number kbotSpeed + * @return number hoverSpeed + * @return number shipSpeed + * @return boolean receiveTracks */ int LuaSyncedRead::GetGroundInfo(lua_State* L) { @@ -7532,10 +7590,10 @@ int LuaSyncedRead::GetGroundBlocked(lua_State* L) /*** * * @function Spring.GetGroundExtremes - * @treturn number initMinHeight - * @treturn number initMaxHeight - * @treturn number currMinHeight - * @treturn number currMaxHeight + * @return number initMinHeight + * @return number initMaxHeight + * @return number currMinHeight + * @return number currMaxHeight */ int LuaSyncedRead::GetGroundExtremes(lua_State* L) { @@ -7550,15 +7608,15 @@ int LuaSyncedRead::GetGroundExtremes(lua_State* L) /*** * * @function Spring.GetTerrainTypeData - * @number terrainTypeInfo - * @treturn number index - * @treturn string name - * @treturn number hardness - * @treturn number tankSpeed - * @treturn number kbotSpeed - * @treturn number hoverSpeed - * @treturn number shipSpeed - * @treturn bool receiveTracks + * @param terrainTypeInfo number + * @return number index + * @return string name + * @return number hardness + * @return number tankSpeed + * @return number kbotSpeed + * @return number hoverSpeed + * @return number shipSpeed + * @return boolean receiveTracks */ int LuaSyncedRead::GetTerrainTypeData(lua_State* L) { @@ -7574,9 +7632,9 @@ int LuaSyncedRead::GetTerrainTypeData(lua_State* L) /*** * * @function Spring.GetGrass - * @number x - * @number z - * @treturn number + * @param x number + * @param z number + * @return number */ int LuaSyncedRead::GetGrass(lua_State* L) { @@ -7590,9 +7648,9 @@ int LuaSyncedRead::GetGrass(lua_State* L) /*** * * @function Spring.GetSmoothMeshHeight - * @number x - * @number z - * @treturn number height + * @param x number + * @param z number + * @return number height */ int LuaSyncedRead::GetSmoothMeshHeight(lua_State* L) { @@ -7614,17 +7672,13 @@ int LuaSyncedRead::GetSmoothMeshHeight(lua_State* L) /*** * * @function Spring.TestMoveOrder - * @number unitDefID - * @number pos.x - * @number pos.y - * @number pos.z - * @number[opt=0] dir.x - * @number[opt=0] dir.y - * @number[opt=0] dir.z - * @bool[opt=true] testTerrain - * @bool[opt=true] testObjects - * @bool[opt=false] centerOnly - * @treturn bool + * @param unitDefID integer + * @param pos float3 + * @param dir float3? (Default: `{ x: 0, y: 0, z: 0 }`) + * @param testTerrain boolean? (Default: true) + * @param testObjects boolean? (Default: true) + * @param centerOnly boolean? (Default: false) + * @return boolean */ int LuaSyncedRead::TestMoveOrder(lua_State* L) { @@ -7669,15 +7723,22 @@ int LuaSyncedRead::TestMoveOrder(lua_State* L) } /*** - * + * @alias BuildOrderBlockedStatus + * | 0 # blocked + * | 1 # mobile unit on the way + * | 2 # reclaimable + * | 3 # open + */ + +/*** * @function Spring.TestBuildOrder - * @number unitDefID - * @number x - * @number y - * @number z - * @tparam number|string facing one of: 0-s,1-e,2-n,3-w - * @treturn number blocking one of: 0 = blocked, 1 = mobile unit on the way, 2 = reclaimable, 3 = open - * @treturn nil|featureID when there's a reclaimable feature on the way + * @param unitDefID integer + * @param x number + * @param y number + * @param z number + * @param facing Facing + * @return BuildOrderBlockedStatus blocking + * @return integer? featureID A reclaimable feature in the way. */ int LuaSyncedRead::TestBuildOrder(lua_State* L) { @@ -7722,14 +7783,14 @@ int LuaSyncedRead::TestBuildOrder(lua_State* L) /*** Snaps a position to the building grid * * @function Spring.Pos2BuildPos - * @number unitDefID - * @number posX - * @number posY - * @number posZ - * @number[opt=0] buildFacing one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3 - * @treturn number buildPosX - * @treturn number buildPosY - * @treturn number buildPosZ + * @param unitDefID integer + * @param posX number + * @param posY number + * @param posZ number + * @param buildFacing number? (Default: 0) one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3 + * @return number buildPosX + * @return number buildPosY + * @return number buildPosZ */ int LuaSyncedRead::Pos2BuildPos(lua_State* L) { @@ -7751,17 +7812,17 @@ int LuaSyncedRead::Pos2BuildPos(lua_State* L) /*** * * @function Spring.ClosestBuildPos - * @number teamID - * @number unitDefID - * @number posX - * @number posY - * @number posZ - * @number searchRadius - * @number minDistance - * @number buildFacing one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3 - * @treturn number buildPosX - * @treturn number buildPosY - * @treturn number buildPosZ + * @param teamID integer + * @param unitDefID integer + * @param posX number + * @param posY number + * @param posZ number + * @param searchRadius number + * @param minDistance number + * @param buildFacing number one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3 + * @return number buildPosX + * @return number buildPosY + * @return number buildPosZ */ int LuaSyncedRead::ClosestBuildPos(lua_State* L) { @@ -7819,14 +7880,14 @@ static int GetEffectiveLosAllyTeam(lua_State* L, int arg) /*** * * @function Spring.GetPositionLosState - * @number posX - * @number posY - * @number posZ - * @number[opt] allyTeamID - * @treturn bool inLosOrRadar - * @treturn inLos - * @treturn inRadar - * @treturn inJammer + * @param posX number + * @param posY number + * @param posZ number + * @param allyTeamID integer? + * @return boolean inLosOrRadar + * @return boolean inLos + * @return boolean inRadar + * @return boolean inJammer */ int LuaSyncedRead::GetPositionLosState(lua_State* L) { @@ -7859,11 +7920,11 @@ int LuaSyncedRead::GetPositionLosState(lua_State* L) /*** * * @function Spring.IsPosInLos - * @number posX - * @number posY - * @number posZ - * @number[opt] allyTeamID - * @treturn bool + * @param posX number + * @param posY number + * @param posZ number + * @param allyTeamID integer? + * @return boolean */ int LuaSyncedRead::IsPosInLos(lua_State* L) { @@ -7885,11 +7946,11 @@ int LuaSyncedRead::IsPosInLos(lua_State* L) /*** * * @function Spring.IsPosInRadar - * @number posX - * @number posY - * @number posZ - * @number[opt] allyTeamID - * @treturn bool + * @param posX number + * @param posY number + * @param posZ number + * @param allyTeamID integer? + * @return boolean */ int LuaSyncedRead::IsPosInRadar(lua_State* L) { @@ -7911,11 +7972,11 @@ int LuaSyncedRead::IsPosInRadar(lua_State* L) /*** * * @function Spring.IsPosInAirLos - * @number posX - * @number posY - * @number posZ - * @number[opt] allyTeamID - * @treturn bool + * @param posX number + * @param posY number + * @param posZ number + * @param allyTeamID integer? + * @return boolean */ int LuaSyncedRead::IsPosInAirLos(lua_State* L) { @@ -7935,20 +7996,26 @@ int LuaSyncedRead::IsPosInAirLos(lua_State* L) /*** - * * @function Spring.GetUnitLosState - * @number unitID - * @number[opt] allyTeamID - * @bool[opt=false] raw - * @treturn nil|number|{los=bool,radar=bool,typed=bool} los - * - * Raw is only available in gadgets and when raw parameter is true. + * @param unitID integer + * @param allyTeamID integer? + * @param raw true Return a bitmask. + * @return integer? bitmask + * A bitmask integer, or `nil` if `unitID` is invalid. * - * RAW returns an bitmask integer, where the bits are: - * 1: LOS_INLOS, the unit is currently in the los of the allyteam, - * 2: LOS_INRADAR the unit is currently in radar from the allyteam, - * 4: LOS_PREVLOS the unit has previously been in los from the allyteam, - * 8: LOS_CONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam + * Bitmask bits: + * - `1`: `LOS_INLOS` the unit is currently in the los of the allyteam, + * - `2`: `LOS_INRADAR` the unit is currently in radar from the allyteam, + * - `4`: `LOS_PREVLOS` the unit has previously been in los from the allyteam, + * - `8`: `LOS_CONTRADAR` the unit has continuously been in radar since it was last inlos by the allyteam + */ +/*** + * @function Spring.GetUnitLosState + * @param unitID integer + * @param allyTeamID integer? + * @param raw false? Return a bitmask. + * @return { los: boolean, radar: boolean, typed: boolean }? los + * A table of LOS state, or `nil` if `unitID` is invalid. */ int LuaSyncedRead::GetUnitLosState(lua_State* L) { @@ -7995,9 +8062,9 @@ int LuaSyncedRead::GetUnitLosState(lua_State* L) /*** * * @function Spring.IsUnitInLos - * @number unitID - * @number allyTeamID - * @treturn bool inLos + * @param unitID integer + * @param allyTeamID integer + * @return boolean inLos */ int LuaSyncedRead::IsUnitInLos(lua_State* L) { @@ -8019,9 +8086,9 @@ int LuaSyncedRead::IsUnitInLos(lua_State* L) /*** * * @function Spring.IsUnitInAirLos - * @number unitID - * @number allyTeamID - * @treturn bool inAirLos + * @param unitID integer + * @param allyTeamID integer + * @return boolean inAirLos */ int LuaSyncedRead::IsUnitInAirLos(lua_State* L) { @@ -8043,9 +8110,9 @@ int LuaSyncedRead::IsUnitInAirLos(lua_State* L) /*** * * @function Spring.IsUnitInRadar - * @number unitID - * @number allyTeamID - * @treturn bool inRadar + * @param unitID integer + * @param allyTeamID integer + * @return boolean inRadar */ int LuaSyncedRead::IsUnitInRadar(lua_State* L) { @@ -8067,9 +8134,9 @@ int LuaSyncedRead::IsUnitInRadar(lua_State* L) /*** * * @function Spring.IsUnitInJammer - * @number unitID - * @number allyTeamID - * @treturn bool inJammer + * @param unitID integer + * @param allyTeamID integer + * @return boolean inJammer */ int LuaSyncedRead::IsUnitInJammer(lua_State* L) { @@ -8212,17 +8279,15 @@ static int GetSolidObjectPieceList(lua_State* L, const CSolidObject* o) } -/*** Piece spec - * - * @table pieceSpec - * - * @string name - * @string parent - * @tparam {[string],...} children names - * @bool empty - * @tparam {number,number,number} min (x,y,z) - * @tparam {number,number,number} max (x,y,z) - * @tparam {number,number,number} offset (x,y,z) +/*** + * @class PieceInfo + * @field name string + * @field parent string + * @field children string[] names + * @field empty boolean + * @field min [number,number,number] (x,y,z) + * @field max [number,number,number] (x,y,z) + * @field offset [number,number,number] (x,y,z) */ @@ -8368,8 +8433,8 @@ static int GetSolidObjectPieceMatrix(lua_State* L, const CSolidObject* o) /*** * * @function Spring.GetModelRootPiece - * @string modelName - * @treturn number index of the root piece + * @param modelName string + * @return number index of the root piece */ int LuaSyncedRead::GetModelRootPiece(lua_State* L) { return ::GetModelRootPiece(L, luaL_optsstring(L, 1, "")); @@ -8378,8 +8443,8 @@ int LuaSyncedRead::GetModelRootPiece(lua_State* L) { /*** * * @function Spring.GetModelPieceMap - * @string modelName - * @treturn nil|{[string]=number,...} pieceInfos where keys are piece names and values are indices + * @param modelName string + * @return nil|table pieceInfos where keys are piece names and values are indices */ int LuaSyncedRead::GetModelPieceMap(lua_State* L) { return ::GetModelPieceMap(L, luaL_optsstring(L, 1, "")); @@ -8389,8 +8454,8 @@ int LuaSyncedRead::GetModelPieceMap(lua_State* L) { /*** * * @function Spring.GetModelPieceList - * @string modelName - * @treturn nil|{[string],...} pieceNames + * @param modelName string + * @return nil|string[] pieceNames */ int LuaSyncedRead::GetModelPieceList(lua_State* L) { return ::GetModelPieceList(L, luaL_optsstring(L, 1, "")); @@ -8400,8 +8465,8 @@ int LuaSyncedRead::GetModelPieceList(lua_State* L) { /*** * * @function Spring.GetUnitRootPiece - * @number unitID - * @treturn number index of the root piece + * @param unitID integer + * @return number index of the root piece */ int LuaSyncedRead::GetUnitRootPiece(lua_State* L) { return (GetSolidObjectRootPiece(L, ParseTypedUnit(L, __func__, 1))); @@ -8410,8 +8475,8 @@ int LuaSyncedRead::GetUnitRootPiece(lua_State* L) { /*** * * @function Spring.GetUnitPieceMap - * @number unitID - * @treturn nil|{[string]=number,...} pieceInfos where keys are piece names and values are indices + * @param unitID integer + * @return nil|table pieceInfos where keys are piece names and values are indices */ int LuaSyncedRead::GetUnitPieceMap(lua_State* L) { return (GetSolidObjectPieceMap(L, ParseTypedUnit(L, __func__, 1))); @@ -8421,8 +8486,8 @@ int LuaSyncedRead::GetUnitPieceMap(lua_State* L) { /*** * * @function Spring.GetUnitPieceList - * @number unitID - * @treturn {[string],...} pieceNames + * @param unitID integer + * @return string[] pieceNames */ int LuaSyncedRead::GetUnitPieceList(lua_State* L) { return (GetSolidObjectPieceList(L, ParseTypedUnit(L, __func__, 1))); @@ -8432,9 +8497,9 @@ int LuaSyncedRead::GetUnitPieceList(lua_State* L) { /*** * * @function Spring.GetUnitPieceInfo - * @number unitID - * @number pieceIndex - * @treturn nil|pieceSpec pieceInfo + * @param unitID integer + * @param pieceIndex integer + * @return PieceInfo? pieceInfo */ int LuaSyncedRead::GetUnitPieceInfo(lua_State* L) { return (GetSolidObjectPieceInfo(L, ParseTypedUnit(L, __func__, 1))); @@ -8444,14 +8509,14 @@ int LuaSyncedRead::GetUnitPieceInfo(lua_State* L) { /*** * * @function Spring.GetUnitPiecePosDir - * @number unitID - * @number pieceIndex - * @treturn number|nil posX - * @treturn number posY - * @treturn number posZ - * @treturn number dirX - * @treturn number dirY - * @treturn number dirZ + * @param unitID integer + * @param pieceIndex integer + * @return number|nil posX + * @return number posY + * @return number posZ + * @return number dirX + * @return number dirY + * @return number dirZ */ int LuaSyncedRead::GetUnitPiecePosDir(lua_State* L) { return (GetSolidObjectPiecePosDir(L, ParseTypedUnit(L, __func__, 1))); @@ -8461,11 +8526,11 @@ int LuaSyncedRead::GetUnitPiecePosDir(lua_State* L) { /*** * * @function Spring.GetUnitPiecePosition - * @number unitID - * @number pieceIndex - * @treturn number|nil posX - * @treturn number posY - * @treturn number posZ + * @param unitID integer + * @param pieceIndex integer + * @return number|nil posX + * @return number posY + * @return number posZ */ int LuaSyncedRead::GetUnitPiecePosition(lua_State* L) { return (GetSolidObjectPiecePosition(L, ParseTypedUnit(L, __func__, 1))); @@ -8475,11 +8540,11 @@ int LuaSyncedRead::GetUnitPiecePosition(lua_State* L) { /*** * * @function Spring.GetUnitPieceDirection - * @number unitID - * @number pieceIndex - * @treturn number|nil dirX - * @treturn number dirY - * @treturn number dirZ + * @param unitID integer + * @param pieceIndex integer + * @return number|nil dirX + * @return number dirY + * @return number dirZ */ int LuaSyncedRead::GetUnitPieceDirection(lua_State* L) { return (GetSolidObjectPieceDirection(L, ParseTypedUnit(L, __func__, 1))); @@ -8489,23 +8554,23 @@ int LuaSyncedRead::GetUnitPieceDirection(lua_State* L) { /*** * * @function Spring.GetUnitPieceMatrix - * @number unitID - * @treturn number|nil m11 - * @treturn number m12 - * @treturn number m13 - * @treturn number m14 - * @treturn number m21 - * @treturn number m22 - * @treturn number m23 - * @treturn number m24 - * @treturn number m31 - * @treturn number m32 - * @treturn number m33 - * @treturn number m34 - * @treturn number m41 - * @treturn number m42 - * @treturn number m43 - * @treturn number m44 + * @param unitID integer + * @return number|nil m11 + * @return number m12 + * @return number m13 + * @return number m14 + * @return number m21 + * @return number m22 + * @return number m23 + * @return number m24 + * @return number m31 + * @return number m32 + * @return number m33 + * @return number m34 + * @return number m41 + * @return number m42 + * @return number m43 + * @return number m44 */ int LuaSyncedRead::GetUnitPieceMatrix(lua_State* L) { return (GetSolidObjectPieceMatrix(L, ParseTypedUnit(L, __func__, 1))); @@ -8514,8 +8579,8 @@ int LuaSyncedRead::GetUnitPieceMatrix(lua_State* L) { /*** * * @function Spring.GetFeatureRootPiece - * @number featureID - * @treturn number index of the root piece + * @param featureID integer + * @return number index of the root piece */ int LuaSyncedRead::GetFeatureRootPiece(lua_State* L) { return (GetSolidObjectRootPiece(L, ParseFeature(L, __func__, 1))); @@ -8524,8 +8589,8 @@ int LuaSyncedRead::GetFeatureRootPiece(lua_State* L) { /*** * * @function Spring.GetFeaturePieceMap - * @number featureID - * @treturn {[string]=number,...} pieceInfos where keys are piece names and values are indices + * @param featureID integer + * @return table pieceInfos where keys are piece names and values are indices */ int LuaSyncedRead::GetFeaturePieceMap(lua_State* L) { return (GetSolidObjectPieceMap(L, ParseFeature(L, __func__, 1))); @@ -8535,8 +8600,8 @@ int LuaSyncedRead::GetFeaturePieceMap(lua_State* L) { /*** * * @function Spring.GetFeaturePieceList - * @number featureID - * @treturn {[string],...} pieceNames + * @param featureID integer + * @return string[] pieceNames */ int LuaSyncedRead::GetFeaturePieceList(lua_State* L) { return (GetSolidObjectPieceList(L, ParseFeature(L, __func__, 1))); @@ -8546,9 +8611,9 @@ int LuaSyncedRead::GetFeaturePieceList(lua_State* L) { /*** * * @function Spring.GetFeaturePieceInfo - * @number featureID - * @number pieceIndex - * @treturn nil|pieceSpec pieceInfo + * @param featureID integer + * @param pieceIndex integer + * @return PieceInfo? pieceInfo */ int LuaSyncedRead::GetFeaturePieceInfo(lua_State* L) { return (GetSolidObjectPieceInfo(L, ParseFeature(L, __func__, 1))); @@ -8558,14 +8623,14 @@ int LuaSyncedRead::GetFeaturePieceInfo(lua_State* L) { /*** * * @function Spring.GetFeaturePiecePosDir - * @number featureID - * @number pieceIndex - * @treturn number|nil posX - * @treturn number posY - * @treturn number posZ - * @treturn number dirX - * @treturn number dirY - * @treturn number dirZ + * @param featureID integer + * @param pieceIndex integer + * @return number|nil posX + * @return number posY + * @return number posZ + * @return number dirX + * @return number dirY + * @return number dirZ */ int LuaSyncedRead::GetFeaturePiecePosDir(lua_State* L) { return (GetSolidObjectPiecePosDir(L, ParseFeature(L, __func__, 1))); @@ -8575,11 +8640,11 @@ int LuaSyncedRead::GetFeaturePiecePosDir(lua_State* L) { /*** * * @function Spring.GetFeaturePiecePosition - * @number featureID - * @number pieceIndex - * @treturn number|nil posX - * @treturn number posY - * @treturn number posZ + * @param featureID integer + * @param pieceIndex integer + * @return number|nil posX + * @return number posY + * @return number posZ */ int LuaSyncedRead::GetFeaturePiecePosition(lua_State* L) { return (GetSolidObjectPiecePosition(L, ParseFeature(L, __func__, 1))); @@ -8589,11 +8654,11 @@ int LuaSyncedRead::GetFeaturePiecePosition(lua_State* L) { /*** * * @function Spring.GetFeaturePieceDirection - * @number featureID - * @number pieceIndex - * @treturn number|nil dirX - * @treturn number dirY - * @treturn number dirZ + * @param featureID integer + * @param pieceIndex integer + * @return number|nil dirX + * @return number dirY + * @return number dirZ */ int LuaSyncedRead::GetFeaturePieceDirection(lua_State* L) { return (GetSolidObjectPieceDirection(L, ParseFeature(L, __func__, 1))); @@ -8603,37 +8668,42 @@ int LuaSyncedRead::GetFeaturePieceDirection(lua_State* L) { /*** * * @function Spring.GetFeaturePieceMatrix - * @number featureID - * @treturn number|nil m11 - * @treturn number m12 - * @treturn number m13 - * @treturn number m14 - * @treturn number m21 - * @treturn number m22 - * @treturn number m23 - * @treturn number m24 - * @treturn number m31 - * @treturn number m32 - * @treturn number m33 - * @treturn number m34 - * @treturn number m41 - * @treturn number m42 - * @treturn number m43 - * @treturn number m44 + * @param featureID integer + * @return number|nil m11 + * @return number m12 + * @return number m13 + * @return number m14 + * @return number m21 + * @return number m22 + * @return number m23 + * @return number m24 + * @return number m31 + * @return number m32 + * @return number m33 + * @return number m34 + * @return number m41 + * @return number m42 + * @return number m43 + * @return number m44 */ int LuaSyncedRead::GetFeaturePieceMatrix(lua_State* L) { return (GetSolidObjectPieceMatrix(L, ParseFeature(L, __func__, 1))); } - /*** * * @function Spring.GetUnitScriptPiece * - * @number unitID - * @number[opt] scriptPiece + * @param unitID integer + * @return integer[] pieceIndices + */ +/*** + * + * @function Spring.GetUnitScriptPiece * - * @treturn {number,...}|number pieceIndices when scriptPiece is not specified, pieceIndex otherwise + * @param unitID integer + * @param scriptPiece integer + * @return integer pieceIndex */ int LuaSyncedRead::GetUnitScriptPiece(lua_State* L) { @@ -8670,9 +8740,9 @@ int LuaSyncedRead::GetUnitScriptPiece(lua_State* L) * * @function Spring.GetUnitScriptNames * - * @number unitID + * @param unitID integer * - * @treturn {[string]=number,...} where keys are piece names and values are piece indices + * @return table where keys are piece names and values are piece indices */ int LuaSyncedRead::GetUnitScriptNames(lua_State* L) { @@ -8716,17 +8786,17 @@ static int TraceRayGroundImpl(lua_State *const L, const float3 &pos, const float * Checks if there is surface (ground, optionally water) towards a vector * and returns the distance to the closest hit and its position, if any. * - * @number posX - * @number posY - * @number posZ - * @number dirX - * @number dirY - * @number dirZ - * @bool[opt=true] testWater - * @treturn number rayLength - * @treturn number posX - * @treturn number posY - * @treturn number posZ + * @param posX number + * @param posY number + * @param posZ number + * @param dirX number + * @param dirY number + * @param dirZ number + * @param testWater boolean? (Default: `true`) + * @return number rayLength + * @return number posX + * @return number posY + * @return number posZ */ int LuaSyncedRead::TraceRayGroundInDirection(lua_State* L) { @@ -8745,17 +8815,17 @@ int LuaSyncedRead::TraceRayGroundInDirection(lua_State* L) * Checks if there is surface (ground, optionally water) between two positions * and returns the distance to the closest hit and its position, if any. * - * @number startX - * @number startY - * @number startZ - * @number endX - * @number endY - * @number endZ - * @bool[opt=true] testWater - * @treturn number rayLength - * @treturn number posX - * @treturn number posY - * @treturn number posZ + * @param startX number + * @param startY number + * @param startZ number + * @param endX number + * @param endY number + * @param endZ number + * @param testWater boolean? (Default: `true`) + * @return number rayLength + * @return number posX + * @return number posY + * @return number posZ */ int LuaSyncedRead::TraceRayGroundBetweenPositions(lua_State* L) { @@ -8780,11 +8850,11 @@ int LuaSyncedRead::TraceRayGroundBetweenPositions(lua_State* L) * * @function Spring.GetRadarErrorParams * - * @number allyTeamID + * @param allyTeamID integer * - * @treturn nil|number radarErrorSize actual radar error size (when allyTeamID is allied to current team) or base radar error size - * @treturn number baseRadarErrorSize - * @treturn number baseRadarErrorMult + * @return number? radarErrorSize actual radar error size (when allyTeamID is allied to current team) or base radar error size + * @return number baseRadarErrorSize + * @return number baseRadarErrorMult */ int LuaSyncedRead::GetRadarErrorParams(lua_State* L) { diff --git a/rts/Lua/LuaTableExtra.cpp b/rts/Lua/LuaTableExtra.cpp index c29cea6fb9..01a51689fe 100644 --- a/rts/Lua/LuaTableExtra.cpp +++ b/rts/Lua/LuaTableExtra.cpp @@ -4,9 +4,7 @@ #include "LuaUtils.h" /****************************************************************************** - * table extensions - * @module TableExtra - * @see rts/Lua/LuaTableExtra.cpp + * Table extensions ******************************************************************************/ /*** Returns a table with preallocated memory @@ -17,9 +15,9 @@ * such as one for each UnitDef, by avoiding reallocation. * * @function table.new - * @number nArray hint for count of array elements - * @number nHashed hint for count of hashtable elements - * @treturn table + * @param nArray number hint for count of array elements + * @param nHashed number hint for count of hashtable elements + * @return table */ static int TableExtra_new(lua_State* L) { diff --git a/rts/Lua/LuaTracyExtra.cpp b/rts/Lua/LuaTracyExtra.cpp index c1f82468d8..617bb0e7dc 100644 --- a/rts/Lua/LuaTracyExtra.cpp +++ b/rts/Lua/LuaTracyExtra.cpp @@ -29,15 +29,19 @@ static const std::string& GetImmanentPlotName(const char *plotName) return *tracyLuaPlots.emplace(plotName).first; } +/** + * Tracy extensions + * @table tracy + */ + /*** Configure custom appearance for a Tracy plot for use in debugging or profiling * * @function tracy.LuaTracyPlotConfig - * @string plotName name of the plot to customize - * @string[opt="Number"] plotFormatType "Number"|"Percentage"|"Memory" - * @bool[opt=true] stepwise stepwise chart - * @bool[opt=false] fill whether to fill color - * @number[opt=0xFFFFFF] color uint32 number as BGR color - * @treturn nil + * @param plotName string name of the plot to customize + * @param plotFormatType "Number"|"Percentage"|"Memory"|nil (Default: `"Number"`) + * @param stepwise boolean? (Default: `true`) stepwise chart + * @param fill boolean? (Default: `false`) whether to fill color + * @param color integer? (Default: `0xFFFFFF`) uint32 number as BGR color */ static int LuaTracyPlotConfig(lua_State* L) @@ -63,9 +67,8 @@ static int LuaTracyPlotConfig(lua_State* L) /*** Update a Tracy plot with a value * * @function tracy.LuaTracyPlot - * @string plotName which LuaPlot should be updated - * @number plotValue the number to show on the Tracy plot - * @treturn nil + * @param plotName string Which LuaPlot should be updated + * @param plotValue number the number to show on the Tracy plot */ static int LuaTracyPlot(lua_State* L) { @@ -76,12 +79,6 @@ static int LuaTracyPlot(lua_State* L) return 0; } -/****************************************************************************** - * tracy extensions - * @module TracyExtra - * @see rts/Lua/LuaTracyExtra.cpp -******************************************************************************/ - bool LuaTracyExtra::PushEntries(lua_State* L) { LuaPushNamedCFunc(L, "LuaTracyPlot" , LuaTracyPlot ); diff --git a/rts/Lua/LuaUnsyncedCtrl.cpp b/rts/Lua/LuaUnsyncedCtrl.cpp index a1031b4a6d..360e12a12a 100644 --- a/rts/Lua/LuaUnsyncedCtrl.cpp +++ b/rts/Lua/LuaUnsyncedCtrl.cpp @@ -115,27 +115,10 @@ /****************************************************************************** * Callouts to set state * - * @module UnsyncedCtrl * @see rts/Lua/LuaUnsyncedCtrl.cpp ******************************************************************************/ -/*** Color triple (RGB) - * @table rgb - * @number r - * @number g - * @number b - */ - -/*** Color quadruple (RGBA) - * @table rgba - * @number r - * @number g - * @number b - * @number a - */ - - bool LuaUnsyncedCtrl::PushEntries(lua_State* L) { REGISTER_LUA_CFUNC(Ping); @@ -469,9 +452,9 @@ static inline CUnit* ParseSelectUnit(lua_State* L, const char* caller, int index * * @function Spring.Ping * - * @number pingTag + * @param pingTag number * - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::Ping(lua_State* L) { @@ -486,39 +469,37 @@ int LuaUnsyncedCtrl::Ping(lua_State* L) /*** Useful for debugging. * - * @function Spring.Echo - * - * @param arg1 - * @param[opt] arg2 - * @param[opt] argn + * Prints values in the spring chat console. + * Hint: the default print() writes to STDOUT. * - * Prints values in the spring chat console. - * Hint: the default print() writes to STDOUT. + * @function Spring.Echo + * @param arg any + * @param ... any * - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::Echo(lua_State* L) { return LuaUtils::Echo(L); } +/*** + * @alias LogLevel + * | integer + * | "debug" # LOG.DEBUG + * | "info" # LOG.INFO + * | "notice" # LOG.NOTICE (engine default) + * | "warning" # LOG.WARNING + * | "deprecated" # LOG.DEPRECATED + * | "error" # LOG.ERROR + * | "fatal" # LOG.FATAL + */ -/*** @function Spring.Log - * @string section - * @tparam ?number|string logLevel - * Possible values for logLevel are: - * "debug" | LOG.DEBUG - * "info" | LOG.INFO - * "notice" | LOG.NOTICE (engine default) - * "deprecated" | LOG.DEPRECATED - * "warning" | LOG.WARNING - * "error" | LOG.ERROR - * "fatal" | LOG.FATAL - * @string logMessage1 - * @string[opt] logMessage2 - * @string[opt] logMessagen - * - * @treturn nil +/*** + * @function Spring.Log + * @param section string + * @param logLevel LogLevel? (Default: "notice") + * @param ... string messages */ int LuaUnsyncedCtrl::Log(lua_State* L) { @@ -526,10 +507,16 @@ int LuaUnsyncedCtrl::Log(lua_State* L) } -/*** @function Spring.SendCommands - * @tparam ?string|table command1 | { command1, command 2, ...} - * @string command2 - * @treturn nil +/*** + * @function Spring.SendCommands + * @param commands string[] + */ + +/*** + * @function Spring.SendCommands + * @param command string + * @param ... string additional commands + * @return nil */ int LuaUnsyncedCtrl::SendCommands(lua_State* L) { @@ -612,8 +599,8 @@ static void PrintMessage(lua_State* L, const string& msg) /*** @function Spring.SendMessage - * @string message - * @treturn nil + * @param message string + * @return nil */ int LuaUnsyncedCtrl::SendMessage(lua_State* L) { @@ -623,8 +610,8 @@ int LuaUnsyncedCtrl::SendMessage(lua_State* L) /*** @function Spring.SendMessageToSpectators - * @string message `` (with # being a playerid) inside the string will be replaced with the players name - i.e. : Spring.SendMessage ("`` did something") might display as "ProRusher did something" - * @treturn nil + * @param message string `` (with # being a playerid) inside the string will be replaced with the players name - i.e. : Spring.SendMessage ("`` did something") might display as "ProRusher did something" + * @return nil */ int LuaUnsyncedCtrl::SendMessageToSpectators(lua_State* L) { @@ -636,9 +623,9 @@ int LuaUnsyncedCtrl::SendMessageToSpectators(lua_State* L) /*** @function Spring.SendMessageToPlayer - * @number playerID - * @string message - * @treturn nil + * @param playerID integer + * @param message string + * @return nil */ int LuaUnsyncedCtrl::SendMessageToPlayer(lua_State* L) { @@ -650,9 +637,9 @@ int LuaUnsyncedCtrl::SendMessageToPlayer(lua_State* L) /*** @function Spring.SendMessageToTeam - * @number teamID - * @string message - * @treturn nil + * @param teamID integer + * @param message string + * @return nil */ int LuaUnsyncedCtrl::SendMessageToTeam(lua_State* L) { @@ -664,9 +651,9 @@ int LuaUnsyncedCtrl::SendMessageToTeam(lua_State* L) /*** @function Spring.SendMessageToAllyTeam - * @number allyID - * @string message - * @treturn nil + * @param allyID integer + * @param message string + * @return nil */ int LuaUnsyncedCtrl::SendMessageToAllyTeam(lua_State* L) { @@ -686,8 +673,8 @@ int LuaUnsyncedCtrl::SendMessageToAllyTeam(lua_State* L) /*** Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`. * * @function Spring.LoadSoundDef - * @string soundfile - * @treturn ?nil|bool success + * @param soundfile string + * @return boolean success */ int LuaUnsyncedCtrl::LoadSoundDef(lua_State* L) { @@ -700,24 +687,32 @@ int LuaUnsyncedCtrl::LoadSoundDef(lua_State* L) return 1; } +/*** + * @alias SoundChannel + * | "general" # 0 + * | "battle" # Same as `"sfx" | 1` + * | "sfx" # Same as `"battle" | 1` + * | "unitreply" # Same as `"voice" | 2` + * | "voice" # Same as `"unitreply" | 2` + * | "userinterface" # Same as "ui" | 3` + * | "ui" # Same as "userinterface" | 3` + * | 0 # General + * | 1 # SFX + * | 2 # Voice + * | 3 # User interface + */ /*** @function Spring.PlaySoundFile - * @string soundfile - * @number[opt=1.0] volume - * @number[opt] posx - * @number[opt] posy - * @number[opt] posz - * @number[opt] speedx - * @number[opt] speedy - * @number[opt] speedz - * @tparam[opt] ?number|string channel - * Possible arguments for channel argument: - * "general" || 0 || nil (default) - * "battle" || "sfx" | 1 - * "unitreply" || "voice" || 2 - * "userinterface" || "ui" || 3 - * - * @treturn ?nil|bool playSound + * @param soundfile string + * @param volume number? (Default: 1.0) + * @param posx number? + * @param posy number? + * @param posz number? + * @param speedx number? + * @param speedy number? + * @param speedz number? + * @param channel SoundChannel? (Default: `0|"general"`) + * @return boolean playSound */ int LuaUnsyncedCtrl::PlaySoundFile(lua_State* L) { @@ -804,11 +799,11 @@ int LuaUnsyncedCtrl::PlaySoundFile(lua_State* L) * * Multiple sound streams may be played at once. * - * @string oggfile - * @number[opt=1.0] volume - * @bool[opt] enqueue + * @param oggfile string + * @param volume number? (Default: 1.0) + * @param enqueue boolean? * - * @treturn ?nil|bool success + * @return boolean success */ int LuaUnsyncedCtrl::PlaySoundStream(lua_State* L) { @@ -825,7 +820,7 @@ int LuaUnsyncedCtrl::PlaySoundStream(lua_State* L) /*** Terminates any SoundStream currently running. * * @function Spring.StopSoundStream - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::StopSoundStream(lua_State*) { @@ -837,7 +832,7 @@ int LuaUnsyncedCtrl::StopSoundStream(lua_State*) /*** Pause any SoundStream currently running. * * @function Spring.PauseSoundStream - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::PauseSoundStream(lua_State*) { @@ -849,8 +844,8 @@ int LuaUnsyncedCtrl::PauseSoundStream(lua_State*) /*** Set volume for SoundStream * * @function Spring.SetSoundStreamVolume - * @number volume - * @treturn nil + * @param volume number + * @return nil */ int LuaUnsyncedCtrl::SetSoundStreamVolume(lua_State* L) { @@ -972,11 +967,11 @@ int LuaUnsyncedCtrl::SetSoundEffectParams(lua_State* L) /*** * * @function Spring.AddWorldIcon - * @number cmdID - * @number posX - * @number posY - * @number posZ - * @treturn nil + * @param cmdID integer + * @param posX number + * @param posY number + * @param posZ number + * @return nil */ int LuaUnsyncedCtrl::AddWorldIcon(lua_State* L) { @@ -992,11 +987,11 @@ int LuaUnsyncedCtrl::AddWorldIcon(lua_State* L) /*** * * @function Spring.AddWorldText - * @string text - * @number posX - * @number posY - * @number posZ - * @treturn nil + * @param text string + * @param posX number + * @param posY number + * @param posZ number + * @return nil */ int LuaUnsyncedCtrl::AddWorldText(lua_State* L) { @@ -1012,13 +1007,13 @@ int LuaUnsyncedCtrl::AddWorldText(lua_State* L) /*** * * @function Spring.AddWorldUnit - * @number unitDefID - * @number posX - * @number posY - * @number posZ - * @number teamID - * @number facing - * @treturn nil + * @param unitDefID integer + * @param posX number + * @param posY number + * @param posZ number + * @param teamID integer + * @param facing number + * @return nil */ int LuaUnsyncedCtrl::AddWorldUnit(lua_State* L) { @@ -1045,16 +1040,16 @@ int LuaUnsyncedCtrl::AddWorldUnit(lua_State* L) /*** * * @function Spring.DrawUnitCommands - * @number unitID - * @treturn nil + * @param unitID integer + * @return nil */ /*** * * @function Spring.DrawUnitCommands - * @tparam table units array of unit ids - * @bool tableOrArray[opt=false] when true `units` is interpreted as a table in the format `{ [unitID] = arg1, ... }` - * @treturn nil + * @param units table array of unit ids + * @param tableOrArray boolean? (Default: false] when true `units` is interpreted as a table in the format `{ [unitID) = arg1, ... }` + * @return nil */ int LuaUnsyncedCtrl::DrawUnitCommands(lua_State* L) { @@ -1093,29 +1088,30 @@ int LuaUnsyncedCtrl::DrawUnitCommands(lua_State* L) * @section camera *****************************************************************************/ -/*** Parameters for camera state - * - * @table camState +/*** + * Parameters for camera state * * Highly dependent on the type of the current camera controller * - * @string name "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy" - * @number mode the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy) - * @number fov - * @number px Position X of the ground point in screen center - * @number py Position Y of the ground point in screen center - * @number pz Position Z of the ground point in screen center - * @number dx Camera direction vector X - * @number dy Camera direction vector Y - * @number dz Camera direction vector Z - * @number rx Camera rotation angle on X axis (spring) - * @number ry Camera rotation angle on Y axis (spring) - * @number rz Camera rotation angle on Z axis (spring) - * @number angle Camera rotation angle on X axis (aka tilt/pitch) (ta) - * @number flipped -1 for when south is down, 1 for when north is down (ta) - * @number dist Camera distance from the ground (spring) - * @number height Camera distance from the ground (ta) - * @number oldHeight Camera distance from the ground, cannot be changed (rot) + * @class camState + * + * @field name "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy" + * @field mode number the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy) + * @field fov number + * @field px number Position X of the ground point in screen center + * @field py number Position Y of the ground point in screen center + * @field pz number Position Z of the ground point in screen center + * @field dx number Camera direction vector X + * @field dy number Camera direction vector Y + * @field dz number Camera direction vector Z + * @field rx number Camera rotation angle on X axis (spring) + * @field ry number Camera rotation angle on Y axis (spring) + * @field rz number Camera rotation angle on Z axis (spring) + * @field angle number Camera rotation angle on X axis (aka tilt/pitch) (ta) + * @field flipped number -1 for when south is down, 1 for when north is down (ta) + * @field dist number Camera distance from the ground (spring) + * @field height number Camera distance from the ground (ta) + * @field oldHeight number Camera distance from the ground, cannot be changed (rot) */ static CCameraController::StateMap ParseCamStateMap(lua_State* L, int tableIdx) @@ -1144,11 +1140,11 @@ static CCameraController::StateMap ParseCamStateMap(lua_State* L, int tableIdx) * * @function Spring.SetCameraTarget * - * @number x - * @number y - * @number z - * @number[opt] transTime - * @treturn nil + * @param x number + * @param y number + * @param z number + * @param transTime number? + * @return nil */ int LuaUnsyncedCtrl::SetCameraTarget(lua_State* L) { @@ -1182,13 +1178,13 @@ int LuaUnsyncedCtrl::SetCameraTarget(lua_State* L) * * @function Spring.SetCameraOffset * - * @number[opt=0] posX - * @number[opt=0] posY - * @number[opt=0] posZ - * @number[opt=0] tiltX - * @number[opt=0] tiltY - * @number[opt=0] tiltZ - * @treturn nil + * @param posX number? (Default: 0) + * @param posY number? (Default: 0) + * @param posZ number? (Default: 0) + * @param tiltX number? (Default: 0) + * @param tiltY number? (Default: 0) + * @param tiltZ number? (Default: 0) + * @return nil */ int LuaUnsyncedCtrl::SetCameraOffset(lua_State* L) { @@ -1209,22 +1205,22 @@ int LuaUnsyncedCtrl::SetCameraOffset(lua_State* L) * * The fields in `camState` must be consistent with the name/mode and current/new camera mode * - * @tparam camState camState - * @number[opt=0] transitionTime in nanoseconds + * @param camState camState + * @param transitionTime number? (Default: 0) in nanoseconds * - * @number[opt] transitionTimeFactor + * @param transitionTimeFactor number? * multiplicative factor applied to this and all subsequent transition times for * this camera mode. * * Defaults to "CamTimeFactor" springsetting unless set previously. * - * @number[opt] transitionTimeExponent + * @param transitionTimeExponent number? * tween factor applied to this and all subsequent transitions for this camera * mode. * * Defaults to "CamTimeExponent" springsetting unless set previously. * - * @treturn bool set + * @return boolean set */ int LuaUnsyncedCtrl::SetCameraState(lua_State* L) { @@ -1251,8 +1247,8 @@ int LuaUnsyncedCtrl::SetCameraState(lua_State* L) /*** Runs Dolly Camera * * @function Spring.RunDollyCamera - * @number runtime in milliseconds - * @treturn nil + * @param runtime number Runtime in milliseconds. + * @return nil */ int LuaUnsyncedCtrl::RunDollyCamera(lua_State* L) { @@ -1266,8 +1262,8 @@ int LuaUnsyncedCtrl::RunDollyCamera(lua_State* L) /*** Pause Dolly Camera * * @function Spring.PauseDollyCamera - * @number fraction fraction of the total runtime to pause at, 0 to 1 inclusive. A null value pauses at current percent - * @treturn nil + * @param fraction number Fraction of the total runtime to pause at, 0 to 1 inclusive. A null value pauses at current percent + * @return nil */ int LuaUnsyncedCtrl::PauseDollyCamera(lua_State* L) { @@ -1281,7 +1277,7 @@ int LuaUnsyncedCtrl::PauseDollyCamera(lua_State* L) /*** Resume Dolly Camera * * @function Spring.ResumeDollyCamera - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::ResumeDollyCamera(lua_State* L) { @@ -1293,10 +1289,10 @@ int LuaUnsyncedCtrl::ResumeDollyCamera(lua_State* L) /*** Sets Dolly Camera Position * * @function Spring.SetDollyCameraPosition - * @number x - * @number y - * @number z - * @treturn nil + * @param x number + * @param y number + * @param z number + * @return nil */ int LuaUnsyncedCtrl::SetDollyCameraPosition(lua_State* L) { @@ -1312,10 +1308,10 @@ int LuaUnsyncedCtrl::SetDollyCameraPosition(lua_State* L) /*** Sets Dolly Camera movement Curve * * @function Spring.SetDollyCameraCurve - * @number degree - * @tparam table cpoints NURBS control point positions {{x,y,z,weight}, ...} - * @tparam table knots - * @treturn nil + * @param degree number + * @param cpoints table NURBS control point positions `{{x,y,z,weight}, ...}` + * @param knots table + * @return nil */ int LuaUnsyncedCtrl::SetDollyCameraCurve(lua_State* L) { @@ -1335,8 +1331,8 @@ int LuaUnsyncedCtrl::SetDollyCameraCurve(lua_State* L) /*** Sets Dolly Camera movement mode * * @function Spring.SetDollyCameraMode - * @number mode 1 static position, 2 nurbs curve - * @treturn nil + * @param mode 1|2 `1` static position, `2` nurbs curve + * @return nil */ int LuaUnsyncedCtrl::SetDollyCameraMode(lua_State* L) { @@ -1350,8 +1346,8 @@ int LuaUnsyncedCtrl::SetDollyCameraMode(lua_State* L) /*** Sets Dolly Camera movement curve to world relative or look target relative * * @function Spring.SetDollyCameraRelativeMode - * @number relativeMode 1 world, 2 look target - * @treturn nil + * @param relativeMode number `1` world, `2` look target + * @return nil */ int LuaUnsyncedCtrl::SetDollyCameraRelativeMode(lua_State* L) { @@ -1366,10 +1362,10 @@ int LuaUnsyncedCtrl::SetDollyCameraRelativeMode(lua_State* L) /*** Sets Dolly Camera Look Curve * * @function Spring.SetDollyCameraLookCurve - * @number degree - * @tparam table cpoints NURBS control point positions {{x,y,z,weight}, ...} - * @tparam table knots - * @treturn nil + * @param degree number + * @param cpoints table NURBS control point positions `{{x,y,z,weight}, ...}` + * @param knots table + * @return nil */ int LuaUnsyncedCtrl::SetDollyCameraLookCurve(lua_State* L) { @@ -1390,10 +1386,10 @@ int LuaUnsyncedCtrl::SetDollyCameraLookCurve(lua_State* L) /*** Sets Dolly Camera Look Position * * @function Spring.SetDollyCameraLookPosition - * @number x - * @number y - * @number z - * @treturn nil + * @param x number + * @param y number + * @param z number + * @return nil */ int LuaUnsyncedCtrl::SetDollyCameraLookPosition(lua_State* L) { @@ -1410,8 +1406,8 @@ int LuaUnsyncedCtrl::SetDollyCameraLookPosition(lua_State* L) /*** Sets target unit for Dolly Camera to look towards * * @function Spring.SetDollyCameraLookUnit - * @number unitID the unit to look at - * @treturn nil + * @param unitID integer The unit to look at. + * @return nil */ int LuaUnsyncedCtrl::SetDollyCameraLookUnit(lua_State* L) { @@ -1433,9 +1429,9 @@ int LuaUnsyncedCtrl::SetDollyCameraLookUnit(lua_State* L) /*** Selects a single unit * * @function Spring.SelectUnit - * @number unitID or nil - * @bool[opt=false] append append to current selection - * @treturn nil + * @param unitID integer? + * @param append boolean? (Default: false) Append to current selection. + * @return nil */ int LuaUnsyncedCtrl::SelectUnit(lua_State* L) { @@ -1457,8 +1453,8 @@ int LuaUnsyncedCtrl::SelectUnit(lua_State* L) /*** * * @function Spring.DeselectUnit - * @number unitID - * @treturn nil + * @param unitID integer + * @return nil */ int LuaUnsyncedCtrl::DeselectUnit(lua_State* L) { @@ -1496,22 +1492,22 @@ static int TableSelectionCommonFunc(lua_State* L, int unitIndexInTable, bool isS return 0; } -/*** Deselects multiple units. Accepts a table with unitIDs as values +/*** Deselects multiple units. * * @function Spring.DeselectUnitArray - * @tparam {[any] = unitID, ...} unitIDs - * @treturn nil + * @param unitIDs table Table with unit IDs as value. + * @return nil */ int LuaUnsyncedCtrl::DeselectUnitArray(lua_State* L) { return TableSelectionCommonFunc(L, -1, false, __func__); } -/*** Deselects multiple units. Accepts a table with unitIDs as keys +/*** Deselects multiple units. * * @function Spring.DeselectUnitMap - * @tparam {[unitID] = any, ...} unitMap where keys are unitIDs - * @treturn nil + * @param unitMap table Table with unit IDs as keys. + * @return nil */ int LuaUnsyncedCtrl::DeselectUnitMap(lua_State* L) { @@ -1521,9 +1517,9 @@ int LuaUnsyncedCtrl::DeselectUnitMap(lua_State* L) /*** Selects multiple units, or appends to selection. Accepts a table with unitIDs as values * * @function Spring.SelectUnitArray - * @tparam {[any] = unitID, ...} unitIDs - * @bool[opt=false] append append to current selection - * @treturn nil + * @param unitMap table Table with unit IDs as values. + * @param append boolean? (Default: false) append to current selection + * @return nil */ int LuaUnsyncedCtrl::SelectUnitArray(lua_State* L) { @@ -1533,9 +1529,9 @@ int LuaUnsyncedCtrl::SelectUnitArray(lua_State* L) /*** Selects multiple units, or appends to selection. Accepts a table with unitIDs as keys * * @function Spring.SelectUnitMap - * @tparam {[unitID] = any, ...} unitMap where keys are unitIDs - * @bool[opt=false] append append to current selection - * @treturn nil + * @param unitMap table Table with unit IDs as keys. + * @param append boolean? (Default: false) append to current selection + * @return nil */ int LuaUnsyncedCtrl::SelectUnitMap(lua_State* L) { @@ -1550,52 +1546,31 @@ int LuaUnsyncedCtrl::SelectUnitMap(lua_State* L) ******************************************************************************/ /*** Parameters for lighting - * @table lightParams - * @tparam table position - * @number position.px - * @number position.py - * @number position.pz - * @tparam table direction - * @number direction.dx - * @number direction.dy - * @number direction.dz - * @tparam table ambientColor - * @number ambientColor.red - * @number ambientColor.green - * @number ambientColor.blue - * @tparam table diffuseColor - * @number diffuseColor.red - * @number diffuseColor.green - * @number diffuseColor.blue - * @tparam table specularColor - * @number specularColor.red - * @number specularColor.green - * @number specularColor.blue - * @tparam table intensityWeight - * @number intensityWeight.ambientWeight - * @number intensityWeight.diffuseWeight - * @number intensityWeight.specularWeight - * @tparam table ambientDecayRate per-frame decay of ambientColor (spread over TTL frames) - * @number ambientDecayRate.ambientRedDecay - * @number ambientDecayRate.ambientGreenDecay - * @number ambientDecayRate.ambientBlueDecay - * @tparam table diffuseDecayRate per-frame decay of diffuseColor (spread over TTL frames) - * @number diffuseDecayRate.diffuseRedDecay - * @number diffuseDecayRate.diffuseGreenDecay - * @number diffuseDecayRate.diffuseBlueDecay - * @tparam table specularDecayRate per-frame decay of specularColor (spread over TTL frames) - * @number specularDecayRate.specularRedDecay - * @number specularDecayRate.specularGreenDecay - * @number specularDecayRate.specularBlueDecay - * @tparam table decayFunctionType *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential - * @number decayFunctionType.ambientDecayType - * @number decayFunctionType.diffuseDecayType - * @number decayFunctionType.specularDecayType - * @number radius - * @number fov - * @number ttl - * @number priority - * @bool ignoreLOS + * + * @class LightParams + * @field position { px: number, py: number, pz: number } + * @field direction { dx: number, dy: number, dz: number } + * @field ambientColor { red: number, green: number, blue: number } + * @field diffuseColor { red: number, green: number, blue: number } + * @field specularColor { red: number, green: number, blue: number } + * @field intensityWeight { ambientWeight: number, diffuseWeight: number, specularWeight: number } + * + * @field ambientDecayRate { ambientRedDecay: number, ambientGreenDecay: number, ambientBlueDecay: number } + * Per-frame decay of `ambientColor` (spread over TTL frames) + * + * @field diffuseDecayRate { diffuseRedDecay: number, diffuseGreenDecay: number, diffuseBlueDecay: number } + * Per-frame decay of `diffuseColor` (spread over TTL frames) + * + * @field specularDecayRate { specularRedDecay: number, specularGreenDecay: number, specularBlueDecay: number } + * Per-frame decay of `specularColor` (spread over TTL frames) + * @field decayFunctionType { ambientDecayType: number, diffuseDecayType: number, specularDecayType: number } + * If value is `0.0` then the `*DecayRate` values will be interpreted as linear, otherwise exponential. + * + * @field radius number + * @field fov number + * @field ttl number + * @field priority number + * @field ignoreLOS boolean */ static bool ParseLight(lua_State* L, GL::Light& light, const int tblIdx, const char* caller) @@ -1713,8 +1688,8 @@ static bool ParseLight(lua_State* L, GL::Light& light, const int tblIdx, const c * * requires MaxDynamicMapLights > 0 * - * @tparam lightParams lightParams - * @treturn number lightHandle + * @param lightParams LightParams + * @return integer lightHandle */ int LuaUnsyncedCtrl::AddMapLight(lua_State* L) { @@ -1739,8 +1714,8 @@ int LuaUnsyncedCtrl::AddMapLight(lua_State* L) * * requires MaxDynamicMapLights > 0 * - * @tparam lightParams lightParams - * @treturn number lightHandle + * @param lightParams LightParams + * @return number lightHandle */ int LuaUnsyncedCtrl::AddModelLight(lua_State* L) { @@ -1763,9 +1738,9 @@ int LuaUnsyncedCtrl::AddModelLight(lua_State* L) /*** * @function Spring.UpdateMapLight * - * @number lightHandle - * @tparam lightParams lightParams - * @treturn bool success + * @param lightHandle number + * @param lightParams LightParams + * @return boolean success */ int LuaUnsyncedCtrl::UpdateMapLight(lua_State* L) { @@ -1785,9 +1760,9 @@ int LuaUnsyncedCtrl::UpdateMapLight(lua_State* L) /*** * @function Spring.UpdateModelLight * - * @number lightHandle - * @tparam lightParams lightParams - * @treturn bool success + * @param lightHandle number + * @param lightParams LightParams + * @return boolean success */ int LuaUnsyncedCtrl::UpdateModelLight(lua_State* L) { @@ -1865,11 +1840,11 @@ static bool AddLightTrackingTarget(lua_State* L, GL::Light* light, bool trackEna * * @function Spring.SetMapLightTrackingState * - * @number lightHandle - * @number unitOrProjectileID - * @bool enableTracking - * @bool unitOrProjectile - * @treturn bool success + * @param lightHandle number + * @param unitOrProjectileID integer + * @param enableTracking boolean + * @param unitOrProjectile boolean + * @return boolean success */ int LuaUnsyncedCtrl::SetMapLightTrackingState(lua_State* L) { @@ -1901,11 +1876,11 @@ int LuaUnsyncedCtrl::SetMapLightTrackingState(lua_State* L) * * @function Spring.SetModelLightTrackingState * - * @number lightHandle - * @number unitOrProjectileID - * @bool enableTracking - * @bool unitOrProjectile - * @treturn bool success + * @param lightHandle number + * @param unitOrProjectileID integer + * @param enableTracking boolean + * @param unitOrProjectile boolean + * @return boolean success */ int LuaUnsyncedCtrl::SetModelLightTrackingState(lua_State* L) { @@ -1945,9 +1920,9 @@ int LuaUnsyncedCtrl::SetModelLightTrackingState(lua_State* L) * Passing in a value of 0 will cause the respective shader to revert back to its engine default. * Custom map shaders that declare a uniform ivec2 named "texSquare" can sample from the default diffuse texture(s), which are always bound to TU 0. * - * @number standardShaderID - * @number deferredShaderID - * @treturn nil + * @param standardShaderID integer + * @param deferredShaderID integer + * @return nil */ int LuaUnsyncedCtrl::SetMapShader(lua_State* L) { @@ -1969,10 +1944,10 @@ int LuaUnsyncedCtrl::SetMapShader(lua_State* L) /*** @function Spring.SetMapSquareTexture - * @number texSqrX - * @number texSqrY - * @string luaTexName - * @treturn bool success + * @param texSqrX number + * @param texSqrY number + * @param luaTexName string + * @return boolean success */ int LuaUnsyncedCtrl::SetMapSquareTexture(lua_State* L) { @@ -2066,9 +2041,9 @@ static MapTextureData ParseLuaTextureData(lua_State* L, bool mapTex) /*** @function Spring.SetMapShadingTexture - * @string texType - * @string texName - * @treturn bool success + * @param texType string + * @param texName string + * @return boolean success * @usage Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture") */ int LuaUnsyncedCtrl::SetMapShadingTexture(lua_State* L) @@ -2087,8 +2062,8 @@ int LuaUnsyncedCtrl::SetMapShadingTexture(lua_State* L) /*** @function Spring.SetSkyBoxTexture - * @string texName - * @treturn nil + * @param texName string + * @return nil */ int LuaUnsyncedCtrl::SetSkyBoxTexture(lua_State* L) { @@ -2111,9 +2086,9 @@ int LuaUnsyncedCtrl::SetSkyBoxTexture(lua_State* L) /*** * * @function Spring.SetUnitNoDraw - * @number unitID - * @bool noDraw - * @treturn nil + * @param unitID integer + * @param noDraw boolean + * @return nil */ int LuaUnsyncedCtrl::SetUnitNoDraw(lua_State* L) { @@ -2130,9 +2105,9 @@ int LuaUnsyncedCtrl::SetUnitNoDraw(lua_State* L) /*** * * @function Spring.SetUnitEngineDrawMask - * @number unitID - * @number drawMask - * @treturn nil + * @param unitID integer + * @param drawMask number + * @return nil */ int LuaUnsyncedCtrl::SetUnitEngineDrawMask(lua_State* L) { @@ -2149,9 +2124,9 @@ int LuaUnsyncedCtrl::SetUnitEngineDrawMask(lua_State* L) /*** * * @function Spring.SetUnitAlwaysUpdateMatrix - * @number unitID - * @bool alwaysUpdateMatrix - * @treturn nil + * @param unitID integer + * @param alwaysUpdateMatrix boolean + * @return nil */ int LuaUnsyncedCtrl::SetUnitAlwaysUpdateMatrix(lua_State* L) { @@ -2168,9 +2143,9 @@ int LuaUnsyncedCtrl::SetUnitAlwaysUpdateMatrix(lua_State* L) /*** * * @function Spring.SetUnitNoMinimap - * @number unitID - * @bool unitNoMinimap - * @treturn nil + * @param unitID integer + * @param unitNoMinimap boolean + * @return nil */ int LuaUnsyncedCtrl::SetUnitNoMinimap(lua_State* L) { @@ -2187,9 +2162,8 @@ int LuaUnsyncedCtrl::SetUnitNoMinimap(lua_State* L) /*** * * @function Spring.SetUnitNoGroup - * @number unitID - * @bool unitNoGroup whether unit can be added to selection groups - * @treturn nil + * @param unitID integer + * @param unitNoGroup boolean Whether unit can be added to selection groups */ int LuaUnsyncedCtrl::SetUnitNoGroup(lua_State* L) { @@ -2210,9 +2184,9 @@ int LuaUnsyncedCtrl::SetUnitNoGroup(lua_State* L) /*** * * @function Spring.SetUnitNoSelect - * @number unitID - * @bool unitNoSelect whether unit can be selected or not - * @treturn nil + * @param unitID integer + * @param unitNoSelect boolean whether unit can be selected or not + * @return nil */ int LuaUnsyncedCtrl::SetUnitNoSelect(lua_State* L) { @@ -2238,9 +2212,9 @@ int LuaUnsyncedCtrl::SetUnitNoSelect(lua_State* L) /*** * * @function Spring.SetUnitLeaveTracks - * @number unitID - * @bool unitLeaveTracks whether unit leaves tracks on movement - * @treturn nil + * @param unitID integer + * @param unitLeaveTracks boolean whether unit leaves tracks on movement + * @return nil */ int LuaUnsyncedCtrl::SetUnitLeaveTracks(lua_State* L) { @@ -2257,18 +2231,18 @@ int LuaUnsyncedCtrl::SetUnitLeaveTracks(lua_State* L) /*** * * @function Spring.SetUnitSelectionVolumeData - * @number unitID - * @number featureID - * @number scaleX - * @number scaleY - * @number scaleZ - * @number offsetX - * @number offsetY - * @number offsetZ - * @number vType - * @number tType - * @number Axis - * @treturn nil + * @param unitID integer + * @param featureID integer + * @param scaleX number + * @param scaleY number + * @param scaleZ number + * @param offsetX number + * @param offsetY number + * @param offsetZ number + * @param vType number + * @param tType number + * @param Axis number + * @return nil */ int LuaUnsyncedCtrl::SetUnitSelectionVolumeData(lua_State* L) { @@ -2291,10 +2265,10 @@ int LuaUnsyncedCtrl::SetUnitSelectionVolumeData(lua_State* L) * * @function Spring.SetFeatureNoDraw * - * @number featureID - * @bool noDraw + * @param featureID integer + * @param noDraw boolean * - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::SetFeatureNoDraw(lua_State* L) { @@ -2311,9 +2285,9 @@ int LuaUnsyncedCtrl::SetFeatureNoDraw(lua_State* L) /*** * * @function Spring.SetFeatureEngineDrawMask - * @number featureID - * @number engineDrawMask - * @treturn nil + * @param featureID integer + * @param engineDrawMask number + * @return nil */ int LuaUnsyncedCtrl::SetFeatureEngineDrawMask(lua_State* L) { @@ -2330,9 +2304,9 @@ int LuaUnsyncedCtrl::SetFeatureEngineDrawMask(lua_State* L) /*** * * @function Spring.SetFeatureAlwaysUpdateMatrix - * @number featureID - * @number alwaysUpdateMat - * @treturn nil + * @param featureID integer + * @param alwaysUpdateMat number + * @return nil */ int LuaUnsyncedCtrl::SetFeatureAlwaysUpdateMatrix(lua_State* L) { @@ -2350,10 +2324,10 @@ int LuaUnsyncedCtrl::SetFeatureAlwaysUpdateMatrix(lua_State* L) * * @function Spring.SetFeatureFade * - * @number featureID - * @bool allow + * @param featureID integer + * @param allow boolean * - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::SetFeatureFade(lua_State* L) { @@ -2371,17 +2345,17 @@ int LuaUnsyncedCtrl::SetFeatureFade(lua_State* L) * * @function Spring.SetFeatureSelectionVolumeData * - * @number featureID - * @number scaleX - * @number scaleY - * @number scaleZ - * @number offsetX - * @number offsetY - * @number offsetZ - * @number vType - * @number tType - * @number Axis - * @treturn nil + * @param featureID integer + * @param scaleX number + * @param scaleY number + * @param scaleZ number + * @param offsetX number + * @param offsetY number + * @param offsetZ number + * @param vType number + * @param tType number + * @param Axis number + * @return nil */ int LuaUnsyncedCtrl::SetFeatureSelectionVolumeData(lua_State* L) { @@ -2405,13 +2379,13 @@ int LuaUnsyncedCtrl::SetFeatureSelectionVolumeData(lua_State* L) * * @function Spring.AddUnitIcon * - * @string iconName - * @string texFile - * @number[opt] size - * @number[opt] dist - * @number[opt] radAdjust + * @param iconName string + * @param texFile string + * @param size number? + * @param dist number? + * @param radAdjust number? * - * @treturn ?nil|bool added + * @return boolean added */ int LuaUnsyncedCtrl::AddUnitIcon(lua_State* L) { @@ -2435,9 +2409,9 @@ int LuaUnsyncedCtrl::AddUnitIcon(lua_State* L) * * @function Spring.FreeUnitIcon * - * @string iconName + * @param iconName string * - * @treturn ?nil|bool freed + * @return boolean? freed */ int LuaUnsyncedCtrl::FreeUnitIcon(lua_State* L) { @@ -2452,11 +2426,11 @@ int LuaUnsyncedCtrl::FreeUnitIcon(lua_State* L) /*** * * @function Spring.UnitIconSetDraw - * Deprecated: use Spring.SetUnitIconDraw instead. - * @see Spring.SetUnitIconDraw - * @number unitID - * @bool drawIcon - * @treturn nil + * Use Spring.SetUnitIconDraw instead. + * @deprecated + * @param unitID integer + * @param drawIcon boolean + * @return nil */ int LuaUnsyncedCtrl::UnitIconSetDraw(lua_State* L) { @@ -2472,9 +2446,9 @@ int LuaUnsyncedCtrl::UnitIconSetDraw(lua_State* L) /*** * * @function Spring.SetUnitIconDraw - * @number unitID - * @bool drawIcon - * @treturn nil + * @param unitID integer + * @param drawIcon boolean + * @return nil */ int LuaUnsyncedCtrl::SetUnitIconDraw(lua_State* L) { @@ -2492,10 +2466,10 @@ int LuaUnsyncedCtrl::SetUnitIconDraw(lua_State* L) * * @function Spring.SetUnitDefIcon * - * @number unitDefID - * @string iconName + * @param unitDefID integer + * @param iconName string * - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::SetUnitDefIcon(lua_State* L) { @@ -2532,10 +2506,10 @@ int LuaUnsyncedCtrl::SetUnitDefIcon(lua_State* L) * * @function Spring.SetUnitDefImage * - * @number unitDefID - * @string image luaTexture|texFile + * @param unitDefID integer + * @param image string luaTexture|texFile * - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::SetUnitDefImage(lua_State* L) { @@ -2583,8 +2557,8 @@ int LuaUnsyncedCtrl::SetUnitDefImage(lua_State* L) /*** * * @function Spring.ExtractModArchiveFile - * @string modfile - * @treturn bool extracted + * @param modfile string + * @return boolean extracted */ int LuaUnsyncedCtrl::ExtractModArchiveFile(lua_State* L) { @@ -2647,8 +2621,8 @@ int LuaUnsyncedCtrl::ExtractModArchiveFile(lua_State* L) /*** * * @function Spring.CreateDir - * @string path - * @treturn ?nil|bool dirCreated + * @param path string + * @return boolean? dirCreated */ int LuaUnsyncedCtrl::CreateDir(lua_State* L) { @@ -2722,22 +2696,23 @@ static int SetActiveCommandByAction(lua_State* L) } -/*** @function Spring.SetActiveCommand - * @string action - * @string[opt] actionExtra - * @treturn ?nil|bool commandSet +/*** + * @function Spring.SetActiveCommand + * @param action string + * @param actionExtra string? + * @return boolean? commandSet */ /*** @function Spring.SetActiveCommand - * @number cmdIndex - * @number[opt=1] button - * @bool[opt] leftClick - * @tparam ?bool rightClick - * @tparam ?bool alt - * @tparam ?bool ctrl - * @tparam ?bool meta - * @tparam ?bool shift - * @treturn ?nil|bool commandSet + * @param cmdIndex number + * @param button number? (Default: 1) + * @param leftClick boolean? + * @param rightClick boolean? + * @param alt boolean? + * @param ctrl boolean? + * @param meta boolean? + * @param shift boolean? + * @return boolean? commandSet */ int LuaUnsyncedCtrl::SetActiveCommand(lua_State* L) { @@ -2761,8 +2736,8 @@ int LuaUnsyncedCtrl::SetActiveCommand(lua_State* L) /*** @function Spring.LoadCmdColorsConfig - * @string config - * @treturn nil + * @param config string + * @return nil */ int LuaUnsyncedCtrl::LoadCmdColorsConfig(lua_State* L) { @@ -2772,8 +2747,8 @@ int LuaUnsyncedCtrl::LoadCmdColorsConfig(lua_State* L) /*** @function Spring.LoadCtrlPanelConfig - * @string config - * @treturn nil + * @param config string + * @return nil */ int LuaUnsyncedCtrl::LoadCtrlPanelConfig(lua_State* L) { @@ -2786,7 +2761,7 @@ int LuaUnsyncedCtrl::LoadCtrlPanelConfig(lua_State* L) /*** @function Spring.ForceLayoutUpdate - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::ForceLayoutUpdate(lua_State* L) { @@ -2801,8 +2776,8 @@ int LuaUnsyncedCtrl::ForceLayoutUpdate(lua_State* L) /*** Disables the "Selected Units x" box in the GUI. * * @function Spring.SetDrawSelectionInfo - * @bool enable - * @treturn nil + * @param enable boolean + * @return nil */ int LuaUnsyncedCtrl::SetDrawSelectionInfo(lua_State* L) { @@ -2816,8 +2791,8 @@ int LuaUnsyncedCtrl::SetDrawSelectionInfo(lua_State* L) /*** * * @function Spring.SetBoxSelectionByEngine - * @bool state - * @treturn nil + * @param state boolean + * @return nil */ int LuaUnsyncedCtrl::SetBoxSelectionByEngine(lua_State* L) { @@ -2830,11 +2805,11 @@ int LuaUnsyncedCtrl::SetBoxSelectionByEngine(lua_State* L) /*** * * @function Spring.SetTeamColor - * @number teamID - * @number r - * @number g - * @number b - * @treturn nil + * @param teamID integer + * @param r number + * @param g number + * @param b number + * @return nil */ int LuaUnsyncedCtrl::SetTeamColor(lua_State* L) { @@ -2858,13 +2833,13 @@ int LuaUnsyncedCtrl::SetTeamColor(lua_State* L) * * @function Spring.AssignMouseCursor * - * @string cmdName - * @string iconFileName not the full filename, instead it is like this: + * @param cmdName string + * @param iconFileName string not the full filename, instead it is like this: * Wanted filename: Anims/cursorattack_0.bmp * => iconFileName: cursorattack - * @bool[opt=true] overwrite - * @bool[opt=false] hotSpotTopLeft - * @treturn ?nil|bool assigned + * @param overwrite boolean? (Default: true) + * @param hotSpotTopLeft boolean? (Default: false) + * @return boolean? assigned */ int LuaUnsyncedCtrl::AssignMouseCursor(lua_State* L) { @@ -2884,10 +2859,10 @@ int LuaUnsyncedCtrl::AssignMouseCursor(lua_State* L) /*** Mass replace all occurrences of the cursor in all CursorCmds. * * @function Spring.ReplaceMouseCursor - * @string oldFileName - * @string newFileName - * @bool[opt=false] hotSpotTopLeft - * @treturn ?nil|bool assigned + * @param oldFileName string + * @param newFileName string + * @param hotSpotTopLeft boolean? (Default: false) + * @return boolean? assigned */ int LuaUnsyncedCtrl::ReplaceMouseCursor(lua_State* L) { @@ -2909,9 +2884,9 @@ int LuaUnsyncedCtrl::ReplaceMouseCursor(lua_State* L) /*** Register your custom cmd so it gets visible in the unit's cmd queue * * @function Spring.SetCustomCommandDrawData - * @number cmdID - * @tparam[opt] string|number cmdReference iconname | cmdID_cloneIcon - * @treturn ?nil|bool assigned + * @param cmdID integer + * @param (string|number)? cmdReference iconname | cmdID_cloneIcon + * @return boolean? assigned */ int LuaUnsyncedCtrl::SetCustomCommandDrawData(lua_State* L) { @@ -2952,9 +2927,9 @@ int LuaUnsyncedCtrl::SetCustomCommandDrawData(lua_State* L) /*** @function Spring.WarpMouse - * @number x - * @number y - * @treturn nil + * @param x number + * @param y number + * @return nil */ int LuaUnsyncedCtrl::WarpMouse(lua_State* L) { @@ -2966,9 +2941,9 @@ int LuaUnsyncedCtrl::WarpMouse(lua_State* L) /*** @function Spring.SetMouseCursor - * @string cursorName - * @number[opt=1.0] cursorScale - * @treturn nil + * @param cursorName string + * @param cursorScale number? (Default: 1.0) + * @return nil */ int LuaUnsyncedCtrl::SetMouseCursor(lua_State* L) { @@ -2987,12 +2962,12 @@ int LuaUnsyncedCtrl::SetMouseCursor(lua_State* L) ******************************************************************************/ /*** @function Spring.SetLosViewColors - * @tparam table always {r,g,b} - * @tparam table LOS = {r,g,b} - * @tparam table radar = {r,g,b} - * @tparam table jam = {r,g,b} - * @tparam table radar2 = {r,g,b} - * @treturn nil + * @param always rgb + * @param LOS rgb + * @param radar rgb + * @param jam rgb + * @param radar2 rgb + * @return nil */ int LuaUnsyncedCtrl::SetLosViewColors(lua_State* L) { @@ -3035,13 +3010,13 @@ int LuaUnsyncedCtrl::SetLosViewColors(lua_State* L) /*** * * @function Spring.SetNanoProjectileParams - * @number[opt=0] rotVal in degrees - * @number[opt=0] rotVel in degrees - * @number[opt=0] rotAcc in degrees - * @number[opt=0] rotValRng in degrees - * @number[opt=0] rotVelRng in degrees - * @number[opt=0] rotAccRng in degrees - * @treturn nil + * @param rotVal number? (Default: 0) in degrees + * @param rotVel number? (Default: 0) in degrees + * @param rotAcc number? (Default: 0) in degrees + * @param rotValRng number? (Default: 0) in degrees + * @param rotVelRng number? (Default: 0) in degrees + * @param rotAccRng number? (Default: 0) in degrees + * @return nil */ int LuaUnsyncedCtrl::SetNanoProjectileParams(lua_State* L) { @@ -3069,10 +3044,10 @@ int LuaUnsyncedCtrl::SetNanoProjectileParams(lua_State* L) /*** * * @function Spring.SetConfigInt - * @string name - * @number value - * @bool[opt=false] useOverlay the value will only be set in memory, and not be restored for the next game. - * @treturn nil + * @param name string + * @param value number + * @param useOverlay boolean? (Default: false) the value will only be set in memory, and not be restored for the next game. + * @return nil */ int LuaUnsyncedCtrl::SetConfigInt(lua_State* L) { @@ -3097,10 +3072,10 @@ int LuaUnsyncedCtrl::SetConfigInt(lua_State* L) /*** * * @function Spring.SetConfigFloat - * @string name - * @number value - * @bool[opt=false] useOverla the value will only be set in memory, and not be restored for the next game.y - * @treturn nil + * @param name string + * @param value number + * @param useOverla boolean? (Default: false) the value will only be set in memory, and not be restored for the next game.y + * @return nil */ int LuaUnsyncedCtrl::SetConfigFloat(lua_State* L) { @@ -3120,10 +3095,10 @@ int LuaUnsyncedCtrl::SetConfigFloat(lua_State* L) /*** * * @function Spring.SetConfigString - * @string name - * @number value - * @bool[opt=false] useOverlay the value will only be set in memory, and not be restored for the next game. - * @treturn nil + * @param name string + * @param value number + * @param useOverlay boolean? (Default: false) the value will only be set in memory, and not be restored for the next game. + * @return nil */ int LuaUnsyncedCtrl::SetConfigString(lua_State* L) { @@ -3198,7 +3173,7 @@ static int ReloadOrRestart(const std::string& springArgs, const std::string& scr /*** Closes the application * * @function Spring.Quit - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::Quit(lua_State* L) { @@ -3214,9 +3189,9 @@ int LuaUnsyncedCtrl::Quit(lua_State* L) /*** * * @function Spring.SetUnitGroup - * @number unitID - * @number groupID the group number to be assigned, or -1 for deassignment - * @treturn nil + * @param unitID integer + * @param groupID number the group number to be assigned, or -1 for deassignment + * @return nil */ int LuaUnsyncedCtrl::SetUnitGroup(lua_State* L) { @@ -3308,26 +3283,26 @@ static bool CanGiveOrders(const lua_State* L) /*** Command Options params * - * @table cmdOpts + * @class cmdOpts * * Can be specified as a table, or as an array containing any of the keys * below. * - * @tparam bool right Right mouse key pressed - * @tparam bool alt Alt key pressed - * @tparam bool ctrl Ctrl key pressed - * @tparam bool shift Shift key pressed - * @tparam bool meta Meta (windows/mac/mod4) key pressed + * @field right boolean Right mouse key pressed + * @field alt boolean Alt key pressed + * @field ctrl boolean Ctrl key pressed + * @field shift boolean Shift key pressed + * @field meta boolean Meta (windows/mac/mod4) key pressed */ /*** * * @function Spring.GiveOrder - * @number cmdID - * @tparam table params - * @tparam cmdOpts options - * @treturn nil|true + * @param cmdID integer + * @param params table + * @param options cmdOpts + * @return nil|true */ int LuaUnsyncedCtrl::GiveOrder(lua_State* L) { @@ -3344,11 +3319,11 @@ int LuaUnsyncedCtrl::GiveOrder(lua_State* L) /*** * * @function Spring.GiveOrderToUnit - * @number unitID - * @number cmdID - * @tparam table params - * @tparam cmdOpts options - * @treturn nil|true + * @param unitID integer + * @param cmdID integer + * @param params table + * @param options cmdOpts + * @return nil|true */ int LuaUnsyncedCtrl::GiveOrderToUnit(lua_State* L) { @@ -3376,11 +3351,11 @@ int LuaUnsyncedCtrl::GiveOrderToUnit(lua_State* L) /*** * * @function Spring.GiveOrderToUnitMap - * @tparam table unitMap { [unitID] = arg1, ... } - * @number cmdID - * @tparam table params - * @tparam cmdOpts options - * @treturn nil|true + * @param unitMap table { [unitID] = arg1, ... } + * @param cmdID integer + * @param params table + * @param options cmdOpts + * @return nil|true */ int LuaUnsyncedCtrl::GiveOrderToUnitMap(lua_State* L) { @@ -3408,11 +3383,11 @@ int LuaUnsyncedCtrl::GiveOrderToUnitMap(lua_State* L) /*** * * @function Spring.GiveOrderToUnitArray - * @tparam {number,...} unitArray array of unit ids - * @number cmdID - * @tparam table params - * @tparam cmdOpts options - * @treturn nil|true + * @param unitArray number[] array of unit ids + * @param cmdID integer + * @param params table + * @param options cmdOpts + * @return nil|true */ int LuaUnsyncedCtrl::GiveOrderToUnitArray(lua_State* L) { @@ -3436,25 +3411,12 @@ int LuaUnsyncedCtrl::GiveOrderToUnitArray(lua_State* L) return 1; } - -/*** Command spec - * - * @table cmdSpec - * - * Used when assigning multiple commands at once - * - * @number cmdID - * @tparam table params - * @tparam cmdOpts options - */ - - /*** * * @function Spring.GiveOrderArrayToUnit - * @number unitID - * @tparam {cmdSpec,...} cmdArray - * @treturn bool ordersGiven + * @param unitID integer + * @param cmdArray Command[] + * @return boolean ordersGiven */ int LuaUnsyncedCtrl::GiveOrderArrayToUnit(lua_State* L) { @@ -3486,9 +3448,9 @@ int LuaUnsyncedCtrl::GiveOrderArrayToUnit(lua_State* L) /*** * * @function Spring.GiveOrderArrayToUnitMap - * @tparam table unitMap { [unitID] = arg1, ... } - * @tparam {cmdSpec,...} cmdArray - * @treturn bool ordersGiven + * @param unitMap table { [unitID] = arg1, ... } + * @param cmdArray Command[] + * @return boolean ordersGiven */ int LuaUnsyncedCtrl::GiveOrderArrayToUnitMap(lua_State* L) { @@ -3520,16 +3482,16 @@ int LuaUnsyncedCtrl::GiveOrderArrayToUnitMap(lua_State* L) /*** * * @function Spring.GiveOrderArrayToUnitArray - * @tparam {number,...} unitArray array of unit ids - * @tparam {cmdSpec,...} cmdArray - * @tparam[opt=false] bool pairwise When false, assign all commands to each unit. + * @param unitArray number[] array of unit ids + * @param cmdArray Command[] + * @param pairwise boolean? (Default: `false`) When `false`, assign all commands to each unit. * - * When true, assign commands according to index between units and cmds arrays. + * When `true`, assign commands according to index between units and cmds arrays. * - * If len(unitArray) < len(cmdArray) only the first len(unitArray) commands + * If `len(unitArray) < len(cmdArray)` only the first `len(unitArray)` commands * will be assigned, and vice-versa. * - * @treturn nil|bool + * @return nil|boolean */ int LuaUnsyncedCtrl::GiveOrderArrayToUnitArray(lua_State* L) { @@ -3563,8 +3525,8 @@ int LuaUnsyncedCtrl::GiveOrderArrayToUnitArray(lua_State* L) /*** * * @function Spring.SetBuildSpacing - * @tparam number spacing - * @treturn nil + * @param spacing number + * @return nil */ int LuaUnsyncedCtrl::SetBuildSpacing(lua_State* L) { @@ -3578,8 +3540,8 @@ int LuaUnsyncedCtrl::SetBuildSpacing(lua_State* L) /*** * * @function Spring.SetBuildFacing - * @tparam number facing - * @treturn nil + * @param facing number + * @return nil */ int LuaUnsyncedCtrl::SetBuildFacing(lua_State* L) { @@ -3598,9 +3560,9 @@ int LuaUnsyncedCtrl::SetBuildFacing(lua_State* L) /*** @function Spring.SendLuaUIMsg - * @string message - * @string mode "s"/"specs" | "a"/"allies" - * @treturn nil + * @param message string + * @param mode string "s"/"specs" | "a"/"allies" + * @return nil */ int LuaUnsyncedCtrl::SendLuaUIMsg(lua_State* L) { @@ -3623,8 +3585,8 @@ int LuaUnsyncedCtrl::SendLuaUIMsg(lua_State* L) /*** @function Spring.SendLuaGaiaMsg - * @string message - * @treturn nil + * @param message string + * @return nil */ int LuaUnsyncedCtrl::SendLuaGaiaMsg(lua_State* L) { @@ -3642,8 +3604,8 @@ int LuaUnsyncedCtrl::SendLuaGaiaMsg(lua_State* L) /*** @function Spring.SendLuaRulesMsg - * @string message - * @treturn nil + * @param message string + * @return nil */ int LuaUnsyncedCtrl::SendLuaRulesMsg(lua_State* L) { @@ -3663,7 +3625,7 @@ int LuaUnsyncedCtrl::SendLuaRulesMsg(lua_State* L) * * @function Spring.SendLuaMenuMsg * - * @string msg + * @param msg string */ int LuaUnsyncedCtrl::SendLuaMenuMsg(lua_State* L) { @@ -3684,9 +3646,9 @@ int LuaUnsyncedCtrl::SendLuaMenuMsg(lua_State* L) * * @function Spring.SetShareLevel * - * @string resource metal | energy - * @number shareLevel - * @treturn nil + * @param resource string metal | energy + * @param shareLevel number + * @return nil */ int LuaUnsyncedCtrl::SetShareLevel(lua_State* L) { @@ -3715,19 +3677,19 @@ int LuaUnsyncedCtrl::SetShareLevel(lua_State* L) * * @function Spring.ShareResources * - * @number teamID - * @string units - * @treturn nil + * @param teamID integer + * @param units string + * @return nil */ /*** * * @function Spring.ShareResources * - * @number teamID - * @string resource metal | energy - * @number amount - * @treturn nil + * @param teamID integer + * @param resource string metal | energy + * @param amount number + * @return nil */ int LuaUnsyncedCtrl::ShareResources(lua_State* L) { @@ -3777,10 +3739,10 @@ int LuaUnsyncedCtrl::ShareResources(lua_State* L) /*** @function Spring.SetLastMessagePosition - * @number x - * @number y - * @number z - * @treturn nil + * @param x number + * @param y number + * @param z number + * @return nil */ int LuaUnsyncedCtrl::SetLastMessagePosition(lua_State* L) { @@ -3800,12 +3762,12 @@ int LuaUnsyncedCtrl::SetLastMessagePosition(lua_State* L) /*** @function Spring.MarkerAddPoint - * @number x - * @number y - * @number z - * @string[opt=""] text - * @bool[opt] localOnly - * @treturn nil + * @param x number + * @param y number + * @param z number + * @param text string? (Default: "") + * @param localOnly boolean? + * @return nil */ int LuaUnsyncedCtrl::MarkerAddPoint(lua_State* L) { @@ -3829,15 +3791,15 @@ int LuaUnsyncedCtrl::MarkerAddPoint(lua_State* L) /*** @function Spring.MarkerAddLine - * @number x1 - * @number y1 - * @number z1 - * @number x2 - * @number y2 - * @number z2 - * @bool[opt=false] localOnly - * @number[opt] playerId - * @treturn nil + * @param x1 number + * @param y1 number + * @param z1 number + * @param x2 number + * @param y2 number + * @param z2 number + * @param localOnly boolean? (Default: false) + * @param playerId number? + * @return nil */ int LuaUnsyncedCtrl::MarkerAddLine(lua_State* L) { @@ -3866,14 +3828,14 @@ int LuaUnsyncedCtrl::MarkerAddLine(lua_State* L) * * Issue an erase command for markers on the map. * - * @number x - * @number y - * @number z - * @param noop - * @bool[opt=false] localOnly do not issue a network message, erase only for the current player - * @number[opt] playerId when not specified it uses the issuer playerId - * @bool[opt=false] alwaysErase erase any marker when `localOnly` and current player is spectating. Allows spectators to erase players markers locally - * @treturn nil + * @param x number + * @param y number + * @param z number + * @param unused nil This argument is ignored. + * @param localOnly boolean? (Default: false) do not issue a network message, erase only for the current player + * @param playerId number? when not specified it uses the issuer playerId + * @param alwaysErase boolean? (Default: false) erase any marker when `localOnly` and current player is spectating. Allows spectators to erase players markers locally + * @return nil */ int LuaUnsyncedCtrl::MarkerErasePosition(lua_State* L) { @@ -3905,17 +3867,24 @@ int LuaUnsyncedCtrl::MarkerErasePosition(lua_State* L) * @section sun ******************************************************************************/ -/*** It can be used to modify the following atmosphere parameters +/*** + * @class AtmosphereParams + * @field fogStart number + * @field fogEnd number + * @field sunColor rgba + * @field skyColor rgba + * @field cloudColor rgba + */ +/*** + * It can be used to modify the following atmosphere parameters + * + * Usage: + * ```lua + * Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }}) + * ``` * * @function Spring.SetAtmosphere - * @tparam table params - * @number params.fogStart - * @number params.fogEnd - * @tparam rgb params.sunColor - * @tparam rgb params.skyColor - * @tparam rgb params.cloudColor - * @usage Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }}) - * @treturn nil + * @param params AtmosphereParams */ int LuaUnsyncedCtrl::SetAtmosphere(lua_State* L) { @@ -3981,11 +3950,11 @@ int LuaUnsyncedCtrl::SetAtmosphere(lua_State* L) /*** * * @function Spring.SetSunDirection - * @number dirX - * @number dirY - * @number dirZ - * @number[opt=true] intensity - * @treturn nil + * @param dirX number + * @param dirY number + * @param dirZ number + * @param intensity number? (Default: `1.0`) + * @return nil */ int LuaUnsyncedCtrl::SetSunDirection(lua_State* L) { @@ -3996,14 +3965,15 @@ int LuaUnsyncedCtrl::SetSunDirection(lua_State* L) } -/*** It can be used to modify the following sun lighting parameters +/*** + * Modify sun lighting parameters. + * + * ```lua + * Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} }) + * ``` * * @function Spring.SetSunLighting - * @tparam table params - * @tparam rgb params.groundAmbientColor - * @tparam rgb params.groundDiffuseColor - * @usage Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} }) - * @treturn nil + * @param params { groundAmbientColor: rgb, groundDiffuseColor: rgb } */ int LuaUnsyncedCtrl::SetSunLighting(lua_State* L) { @@ -4043,21 +4013,20 @@ int LuaUnsyncedCtrl::SetSunLighting(lua_State* L) /*** Map rendering params * - * @table mapRenderingParams - * - * @tparam rgba splatTexMults - * @tparam rgba splatTexScales - * @bool voidWater - * @bool voidGround - * @bool splatDetailNormalDiffuseAlpha + * @class MapRenderingParams + * @field splatTexMults rgba + * @field splatTexScales rgba + * @field voidWater boolean + * @field voidGround boolean + * @field splatDetailNormalDiffuseAlpha boolean */ /*** Allows to change map rendering params at runtime. * * @function Spring.SetMapRenderingParams - * @tparam mapRenderingParams params - * @treturn nil + * @param params MapRenderingParams + * @return nil */ int LuaUnsyncedCtrl::SetMapRenderingParams(lua_State* L) { @@ -4122,9 +4091,9 @@ int LuaUnsyncedCtrl::SetMapRenderingParams(lua_State* L) /*** * * @function Spring.ForceTesselationUpdate - * @bool[opt=true] normal - * @bool[opt=false] shadow - * @treturn bool updated + * @param normal boolean? (Default: true) + * @param shadow boolean? (Default: false) + * @return boolean updated */ int LuaUnsyncedCtrl::ForceTesselationUpdate(lua_State* L) { @@ -4158,9 +4127,9 @@ int LuaUnsyncedCtrl::ForceTesselationUpdate(lua_State* L) /*** @function Spring.SendSkirmishAIMessage - * @number aiTeam - * @string message - * @treturn ?nil|bool ai_processed + * @param aiTeam number + * @param message string + * @return boolean? ai_processed */ int LuaUnsyncedCtrl::SendSkirmishAIMessage(lua_State* L) { if (CLuaHandle::GetHandleSynced(L)) @@ -4192,9 +4161,9 @@ int LuaUnsyncedCtrl::SendSkirmishAIMessage(lua_State* L) { /*** @function Spring.SetLogSectionFilterLevel - * @string sectionName - * @tparam ?string|number logLevel - * @treturn nil + * @param sectionName string + * @param logLevel ?string|number + * @return nil */ int LuaUnsyncedCtrl::SetLogSectionFilterLevel(lua_State* L) { const int loglevel = LuaUtils::ParseLogLevel(L, 2); @@ -4208,15 +4177,15 @@ int LuaUnsyncedCtrl::SetLogSectionFilterLevel(lua_State* L) { /*** @function Spring.GarbageCollectCtrl * - * @int[opt] itersPerBatch - * @int[opt] numStepsPerIter - * @int[opt] minStepsPerIter - * @int[opt] maxStepsPerIter - * @number[opt] minLoopRunTime - * @number[opt] maxLoopRunTime - * @number[opt] baseRunTimeMult - * @number[opt] baseMemLoadMult - * @treturn nil + * @param itersPerBatch integer? + * @param numStepsPerIter integer? + * @param minStepsPerIter integer? + * @param maxStepsPerIter integer? + * @param minLoopRunTime number? + * @param maxLoopRunTime number? + * @param baseRunTimeMult number? + * @param baseMemLoadMult number? + * @return nil */ int LuaUnsyncedCtrl::GarbageCollectCtrl(lua_State* L) { luaContextData* ctxData = GetLuaContextData(L); @@ -4239,8 +4208,8 @@ int LuaUnsyncedCtrl::GarbageCollectCtrl(lua_State* L) { /*** @function Spring.SetDrawSky - * @bool drawSky - * @treturn nil + * @param drawSky boolean + * @return nil */ int LuaUnsyncedCtrl::SetDrawSky(lua_State* L) { @@ -4250,8 +4219,8 @@ int LuaUnsyncedCtrl::SetDrawSky(lua_State* L) /*** @function Spring.SetDrawWater - * @bool drawWater - * @treturn nil + * @param drawWater boolean + * @return nil */ int LuaUnsyncedCtrl::SetDrawWater(lua_State* L) { @@ -4261,8 +4230,8 @@ int LuaUnsyncedCtrl::SetDrawWater(lua_State* L) /*** @function Spring.SetDrawGround - * @bool drawGround - * @treturn nil + * @param drawGround boolean + * @return nil */ int LuaUnsyncedCtrl::SetDrawGround(lua_State* L) { @@ -4272,9 +4241,9 @@ int LuaUnsyncedCtrl::SetDrawGround(lua_State* L) /*** @function Spring.SetDrawGroundDeferred - * @bool drawGroundDeferred - * @bool[opt] drawGroundForward allows disabling of the forward pass - * treturn nil + * @param drawGroundDeferred boolean + * @param drawGroundForward boolean? allows disabling of the forward pass + * @return nil */ int LuaUnsyncedCtrl::SetDrawGroundDeferred(lua_State* L) { @@ -4289,11 +4258,11 @@ int LuaUnsyncedCtrl::SetDrawGroundDeferred(lua_State* L) } /*** @function Spring.SetDrawModelsDeferred - * @bool drawUnitsDeferred - * @bool drawFeaturesDeferred - * @bool[opt] drawUnitsForward allows disabling of the respective forward passes - * @bool[opt] drawFeaturesForward allows disabling of the respective forward passes - * @treturn nil + * @param drawUnitsDeferred boolean + * @param drawFeaturesDeferred boolean + * @param drawUnitsForward boolean? allows disabling of the respective forward passes + * @param drawFeaturesForward boolean? allows disabling of the respective forward passes + * @return nil */ int LuaUnsyncedCtrl::SetDrawModelsDeferred(lua_State* L) { @@ -4315,8 +4284,8 @@ int LuaUnsyncedCtrl::SetDrawModelsDeferred(lua_State* L) /*** This doesn't actually record the game in any way, it just regulates the framerate and interpolations. * * @function Spring.SetVideoCapturingMode - * @bool allowCaptureMode - * @treturn nil + * @param allowCaptureMode boolean + * @return nil */ int LuaUnsyncedCtrl::SetVideoCapturingMode(lua_State* L) { @@ -4326,8 +4295,8 @@ int LuaUnsyncedCtrl::SetVideoCapturingMode(lua_State* L) /*** @function Spring.SetVideoCapturingTimeOffset - * @bool timeOffset - * @treturn nil + * @param timeOffset boolean + * @return nil */ int LuaUnsyncedCtrl::SetVideoCapturingTimeOffset(lua_State* L) { @@ -4336,51 +4305,60 @@ int LuaUnsyncedCtrl::SetVideoCapturingTimeOffset(lua_State* L) } -/*** Water params - * - * @table waterParams - * - * @tparam rgb absorb - * @tparam rgb baseColor - * @tparam rgb minColor - * @tparam rgb surfaceColor - * @tparam rgb diffuseColor - * @tparam rgb specularColor - * @tparam rgb planeColor - * @string texture file - * @string foamTexture file - * @string normalTexture file - * @number damage - * @number repeatX - * @number repeatY - * @number surfaceAlpha - * @number ambientFactor - * @number diffuseFactor - * @number specularFactor - * @number specularPower - * @number fresnelMin - * @number fresnelMax - * @number fresnelPower - * @number reflectionDistortion - * @number blurBase - * @number blurExponent - * @number perlinStartFreq - * @number perlinLacunarity - * @number perlinAmplitude - * @number numTiles - * @bool shoreWaves - * @bool forceRendering - * @bool hasWaterPlane - */ - - -/*** @function Spring.SetWaterParams - * - * Does not need cheating enabled. - * Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your springrc to 1, then you don't even need to restart BumpWater via `/water 4`. - * - * @tparam waterParams waterParams - * @treturn nil +/*** + * Water params + * + * @class WaterParams + * @field absorb rgb + * @field baseColor rgb + * @field minColor rgb + * @field surfaceColor rgb + * @field diffuseColor rgb + * @field specularColor rgb + * @field planeColor rgb + * @field texture string file + * @field foamTexture string file + * @field normalTexture string file + * @field damage number + * @field repeatX number + * @field repeatY number + * @field surfaceAlpha number + * @field ambientFactor number + * @field diffuseFactor number + * @field specularFactor number + * @field specularPower number + * @field fresnelMin number + * @field fresnelMax number + * @field fresnelPower number + * @field reflectionDistortion number + * @field blurBase number + * @field blurExponent number + * @field perlinStartFreq number + * @field perlinLacunarity number + * @field perlinAmplitude number + * @field windSpeed number + * @field waveOffsetFactor number + * @field waveLength number + * @field waveFoamDistortion number + * @field waveFoamIntensity number + * @field causticsResolution number + * @field causticsStrength number + * @field numTiles integer + * @field shoreWaves boolean + * @field forceRendering boolean + * @field hasWaterPlane boolean + */ + +/*** + * Does not need cheating enabled. + * + * Allows to change water params (mostly `BumpWater` ones) at runtime. You may + * want to set `BumpWaterUseUniforms` in your `springrc` to 1, then you don't even + * need to restart `BumpWater` via `/water 4`. + * + * @function Spring.SetWaterParams + * @param waterParams WaterParams + * @return nil */ int LuaUnsyncedCtrl::SetWaterParams(lua_State* L) { @@ -4596,8 +4574,8 @@ int LuaUnsyncedCtrl::SetWaterParams(lua_State* L) * Allow the engine to load the unit's model (and texture) in a background thread. * Wreckages and buildOptions of a unit are automatically preloaded. * - * @number unitDefID - * @treturn nil + * @param unitDefID integer + * @return nil */ int LuaUnsyncedCtrl::PreloadUnitDefModel(lua_State* L) { const UnitDef* ud = unitDefHandler->GetUnitDefByID(luaL_checkint(L, 1)); @@ -4612,8 +4590,8 @@ int LuaUnsyncedCtrl::PreloadUnitDefModel(lua_State* L) { /*** @function Spring.PreloadFeatureDefModel * - * @number featureDefID - * @treturn nil + * @param featureDefID integer + * @return nil */ int LuaUnsyncedCtrl::PreloadFeatureDefModel(lua_State* L) { const FeatureDef* fd = featureDefHandler->GetFeatureDefByID(luaL_checkint(L, 1)); @@ -4628,8 +4606,8 @@ int LuaUnsyncedCtrl::PreloadFeatureDefModel(lua_State* L) { /*** @function Spring.PreloadSoundItem * - * @string name - * @treturn nil + * @param name string + * @return nil */ int LuaUnsyncedCtrl::PreloadSoundItem(lua_State* L) { @@ -4644,8 +4622,8 @@ int LuaUnsyncedCtrl::PreloadSoundItem(lua_State* L) /*** @function Spring.LoadModelTextures * - * @string modelName - * @treturn ?nil|bool success + * @param modelName string + * @return boolean? success */ int LuaUnsyncedCtrl::LoadModelTextures(lua_State* L) { @@ -4681,7 +4659,7 @@ int LuaUnsyncedCtrl::LoadModelTextures(lua_State* L) /*** * * @function Spring.CreateGroundDecal - * @treturn nil|number decalID + * @return nil|number decalID */ int LuaUnsyncedCtrl::CreateGroundDecal(lua_State* L) { @@ -4697,8 +4675,8 @@ int LuaUnsyncedCtrl::CreateGroundDecal(lua_State* L) /*** * * @function Spring.DestroyGroundDecal - * @number decalID - * @treturn bool delSuccess + * @param decalID integer + * @return boolean delSuccess */ int LuaUnsyncedCtrl::DestroyGroundDecal(lua_State* L) { @@ -4710,13 +4688,13 @@ int LuaUnsyncedCtrl::DestroyGroundDecal(lua_State* L) /*** * * @function Spring.SetGroundDecalPosAndDims - * @number decalID - * @number[opt=currMidPosX] midPosX - * @number[opt=currMidPosZ] midPosZ - * @number[opt=currSizeX] sizeX - * @number[opt=currSizeZ] sizeZ - * @number[opt=calculateProjCubeHeight] projCubeHeight - * @treturn bool decalSet + * @param decalID integer + * @param midPosX number? (Default: currMidPosX) + * @param midPosZ number? (Default: currMidPosZ) + * @param sizeX number? (Default: currSizeX) + * @param sizeZ number? (Default: currSizeZ) + * @param projCubeHeight number? (Default: calculateProjCubeHeight) + * @return boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalPosAndDims(lua_State* L) { @@ -4751,23 +4729,24 @@ int LuaUnsyncedCtrl::SetGroundDecalPosAndDims(lua_State* L) return 1; } +/*** + * @class xz + * @field x number + * @field y number + */ /*** * * @function Spring.SetGroundDecalQuadPosAndHeight * * Use for non-rectangular decals * - * @number decalID - * @number[opt=currPosTL.x] posTL.x - * @number[opt=currPosTL.z] posTL.z - * @number[opt=currPosTR.x] posTR.x - * @number[opt=currPosTR.z] posTR.z - * @number[opt=currPosBR.x] posBR.x - * @number[opt=currPosBR.z] posBR.z - * @number[opt=currPosBL.x] posBL.x - * @number[opt=currPosBL.z] posBL.z - * @number[opt=calculateProjCubeHeight] projCubeHeight - * @treturn bool decalSet + * @param decalID integer + * @param posTL xz? (Default: currPosTL) + * @param posTR xz? (Default: currPosTR) + * @param posBR xz? (Default: currPosBR) + * @param posBL xz? (Default: currPosBL) + * @param projCubeHeight number? (Default: calculateProjCubeHeight) + * @return boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalQuadPosAndHeight(lua_State* L) { @@ -4794,9 +4773,9 @@ int LuaUnsyncedCtrl::SetGroundDecalQuadPosAndHeight(lua_State* L) /*** * * @function Spring.SetGroundDecalRotation - * @number decalID - * @number[opt=random] rot in radians - * @treturn bool decalSet + * @param decalID integer + * @param rot number? (Default: random) in radians + * @return boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalRotation(lua_State* L) { @@ -4816,10 +4795,10 @@ int LuaUnsyncedCtrl::SetGroundDecalRotation(lua_State* L) /*** * * @function Spring.SetGroundDecalTexture - * @number decalID - * @string textureName The texture has to be on the atlas which seems to mean it's defined as an explosion, unit tracks, or building plate decal on some unit already (no arbitrary textures) - * @bool[opt=true] isMainTex If false, it sets the normals/glow map - * @treturn nil|bool decalSet + * @param decalID integer + * @param textureName string The texture has to be on the atlas which seems to mean it's defined as an explosion, unit tracks, or building plate decal on some unit already (no arbitrary textures) + * @param isMainTex boolean? (Default: true) If false, it sets the normals/glow map + * @return nil|boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalTexture(lua_State* L) { @@ -4832,10 +4811,10 @@ int LuaUnsyncedCtrl::SetGroundDecalTexture(lua_State* L) /*** * * @function Spring.SetGroundDecalTextureParams - * @number decalID - * @number texWrapDistance[opt=currTexWrapDistance] if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos - * @number texTraveledDistance[opt=currTexTraveledDistance] shifts the texture repetition defined by texWrapFactor so the texture of a next line in the continuous multiline can start where the previous finished. For that it should collect all elmo lengths of the previously set multiline segments. - * @treturn nil|bool decalSet + * @param decalID integer + * @param texWrapDistance number? (Default: currTexWrapDistance) if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos + * @param texTraveledDistance number? (Default: currTexTraveledDistance) shifts the texture repetition defined by texWrapFactor so the texture of a next line in the continuous multiline can start where the previous finished. For that it should collect all elmo lengths of the previously set multiline segments. + * @return nil|boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalTextureParams(lua_State* L) { @@ -4856,10 +4835,10 @@ int LuaUnsyncedCtrl::SetGroundDecalTextureParams(lua_State* L) /*** * * @function Spring.SetGroundDecalAlpha - * @number decalID - * @number[opt=currAlpha] alpha Between 0 and 1 - * @number[opt=currAlphaFalloff] alphaFalloff Between 0 and 1, per second - * @treturn bool decalSet + * @param decalID integer + * @param alpha number? (Default: currAlpha) Between 0 and 1 + * @param alphaFalloff number? (Default: currAlphaFalloff) Between 0 and 1, per second + * @return boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalAlpha(lua_State* L) { @@ -4881,11 +4860,11 @@ int LuaUnsyncedCtrl::SetGroundDecalAlpha(lua_State* L) * @function Spring.SetGroundDecalNormal * Sets projection cube normal to orient in 3D space. * In case the normal (0,0,0) then normal is picked from the terrain - * @number decalID - * @number[opt=0] normalX - * @number[opt=0] normalY - * @number[opt=0] normalZ - * @treturn bool decalSet + * @param decalID integer + * @param normalX number? (Default: 0) + * @param normalY number? (Default: 0) + * @param normalZ number? (Default: 0) + * @return boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalNormal(lua_State* L) { @@ -4913,12 +4892,12 @@ int LuaUnsyncedCtrl::SetGroundDecalNormal(lua_State* L) * @function Spring.SetGroundDecalTint * Sets the tint of the ground decal. Color = 2 * textureColor * tintColor * Respectively a color of (0.5, 0.5, 0.5, 0.5) is effectively no tint - * @number decalID - * @number[opt=curTintColR] tintColR - * @number[opt=curTintColG] tintColG - * @number[opt=curTintColB] tintColB - * @number[opt=curTintColA] tintColA - * @treturn bool decalSet + * @param decalID integer + * @param tintColR number? (Default: curTintColR) + * @param tintColG number? (Default: curTintColG) + * @param tintColB number? (Default: curTintColB) + * @param tintColA number? (Default: curTintColA) + * @return boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalTint(lua_State* L) { @@ -4944,13 +4923,13 @@ int LuaUnsyncedCtrl::SetGroundDecalTint(lua_State* L) * * @function Spring.SetGroundDecalMisc * Sets varios secondary parameters of a decal - * @number decalID - * @number[opt=curValue] dotElimExp pow(max(dot(decalProjVector, SurfaceNormal), 0.0), dotElimExp), used to reduce decal artifacts on surfaces non-collinear with the projection vector - * @number[opt=curValue] refHeight - * @number[opt=curValue] minHeight - * @number[opt=curValue] maxHeight - * @number[opt=curValue] forceHeightMode in case forceHeightMode==1.0 ==> force relative height: midPoint.y = refHeight + clamp(midPoint.y - refHeight, minHeight); forceHeightMode==2.0 ==> force absolute height: midPoint.y = midPoint.y, clamp(midPoint.y, minHeight, maxHeight); other forceHeightMode values do not enforce the height of the center position - * @treturn bool decalSet + * @param decalID integer + * @param dotElimExp number? (Default: curValue) pow(max(dot(decalProjVector, SurfaceNormal), 0.0), dotElimExp), used to reduce decal artifacts on surfaces non-collinear with the projection vector + * @param refHeight number? (Default: curValue) + * @param minHeight number? (Default: curValue) + * @param maxHeight number? (Default: curValue) + * @param forceHeightMode number? (Default: curValue) in case forceHeightMode==1.0 ==> force relative height: midPoint.y = refHeight + clamp(midPoint.y - refHeight, minHeight); forceHeightMode==2.0 ==> force absolute height: midPoint.y = midPoint.y, clamp(midPoint.y, minHeight, maxHeight); other forceHeightMode values do not enforce the height of the center position + * @return boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalMisc(lua_State* L) { @@ -4976,10 +4955,10 @@ int LuaUnsyncedCtrl::SetGroundDecalMisc(lua_State* L) * * Use separate min and max for "gradient" style decals such as tank tracks * - * @number decalID - * @number[opt=currCreationFrameMin] creationFrameMin - * @number[opt=currCreationFrameMax] creationFrameMax - * @treturn bool decalSet + * @param decalID integer + * @param creationFrameMin number? (Default: currCreationFrameMin) + * @param creationFrameMax number? (Default: currCreationFrameMax) + * @return boolean decalSet */ int LuaUnsyncedCtrl::SetGroundDecalCreationFrame(lua_State* L) { @@ -5006,11 +4985,11 @@ int LuaUnsyncedCtrl::SetGroundDecalCreationFrame(lua_State* L) /*** * * @function Spring.SDLSetTextInputRect - * @number x - * @number y - * @number width - * @number height - * @treturn nil + * @param x number + * @param y number + * @param width number + * @param height number + * @return nil */ int LuaUnsyncedCtrl::SDLSetTextInputRect(lua_State* L) { @@ -5026,7 +5005,7 @@ int LuaUnsyncedCtrl::SDLSetTextInputRect(lua_State* L) /*** * * @function Spring.SDLStartTextInput - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::SDLStartTextInput(lua_State* L) { @@ -5037,7 +5016,7 @@ int LuaUnsyncedCtrl::SDLStartTextInput(lua_State* L) /*** * * @function Spring.SDLStopTextInput - * @treturn nil + * @return nil */ int LuaUnsyncedCtrl::SDLStopTextInput(lua_State* L) { @@ -5054,14 +5033,14 @@ int LuaUnsyncedCtrl::SDLStopTextInput(lua_State* L) /*** * * @function Spring.SetWindowGeometry - * @number displayIndex - * @number winRelPosX - * @number winRelPosY - * @number winSizeX - * @number winSizeY - * @bool fullScreen - * @bool borderless - * @treturn nil + * @param displayIndex number + * @param winRelPosX number + * @param winRelPosY number + * @param winSizeX number + * @param winSizeY number + * @param fullScreen boolean + * @param borderless boolean + * @return nil */ int LuaUnsyncedCtrl::SetWindowGeometry(lua_State* L) { @@ -5084,7 +5063,7 @@ int LuaUnsyncedCtrl::SetWindowGeometry(lua_State* L) /*** * * @function Spring.SetWindowMinimized - * @treturn bool minimized + * @return boolean minimized */ int LuaUnsyncedCtrl::SetWindowMinimized(lua_State* L) { @@ -5095,7 +5074,7 @@ int LuaUnsyncedCtrl::SetWindowMinimized(lua_State* L) /*** * * @function Spring.SetWindowMaximized - * @treturn bool maximized + * @return boolean maximized */ int LuaUnsyncedCtrl::SetWindowMaximized(lua_State* L) { @@ -5111,8 +5090,8 @@ int LuaUnsyncedCtrl::SetWindowMaximized(lua_State* L) /*** @function Spring.Reload - * @string startScript the CONTENT of the script.txt spring should use to start. - * @treturn nil + * @param startScript string the CONTENT of the script.txt spring should use to start. + * @return nil */ int LuaUnsyncedCtrl::Reload(lua_State* L) { @@ -5124,9 +5103,9 @@ int LuaUnsyncedCtrl::Reload(lua_State* L) * * If this call returns, something went wrong * - * @string commandline_args commandline arguments passed to spring executable. - * @string startScript - * @treturn nil + * @param commandline_args string commandline arguments passed to spring executable. + * @param startScript string + * @return nil */ int LuaUnsyncedCtrl::Restart(lua_State* L) { @@ -5141,9 +5120,9 @@ int LuaUnsyncedCtrl::Restart(lua_State* L) * * If this call returns, something went wrong * - * @string commandline_args commandline arguments passed to spring executable. - * @string startScript the CONTENT of the script.txt spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to commandline_args. - * @treturn nil + * @param commandline_args string commandline arguments passed to spring executable. + * @param startScript string the CONTENT of the script.txt spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to commandline_args. + * @return nil */ int LuaUnsyncedCtrl::Start(lua_State* L) { @@ -5165,8 +5144,8 @@ int LuaUnsyncedCtrl::Start(lua_State* L) * Note: *.bmp images have to be in BGR format (default for m$ ones). * Note: *.ico images are not supported. * - * @string iconFileName - * @treturn nil + * @param iconFileName string + * @return nil */ int LuaUnsyncedCtrl::SetWMIcon(lua_State* L) { @@ -5193,9 +5172,9 @@ int LuaUnsyncedCtrl::SetWMIcon(lua_State* L) * * NOTE: shortTitle is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows. * - * @string title - * @string[opt=title] titleShort - * @treturn nil + * @param title string + * @param titleShort string? (Default: title) + * @return nil */ int LuaUnsyncedCtrl::SetWMCaption(lua_State* L) { @@ -5205,8 +5184,8 @@ int LuaUnsyncedCtrl::SetWMCaption(lua_State* L) /*** @function Spring.ClearWatchDogTimer - * @string[opt=main] threadName - * @treturn nil + * @param threadName string? (Default: main) + * @return nil */ int LuaUnsyncedCtrl::ClearWatchDogTimer(lua_State* L) { if (lua_gettop(L) == 0) { @@ -5226,8 +5205,8 @@ int LuaUnsyncedCtrl::ClearWatchDogTimer(lua_State* L) { /*** @function Spring.SetClipboard - * @string text - * @treturn nil + * @param text string + * @return nil */ int LuaUnsyncedCtrl::SetClipboard(lua_State* L) { @@ -5249,7 +5228,7 @@ int LuaUnsyncedCtrl::SetClipboard(lua_State* L) * wantYield = wantYield and Spring.Yield() * end * - * @treturn bool when true caller should continue calling `Spring.Yield` during the widgets/gadgets load, when false it shouldn't call it any longer. + * @return boolean when true caller should continue calling `Spring.Yield` during the widgets/gadgets load, when false it shouldn't call it any longer. */ int LuaUnsyncedCtrl::Yield(lua_State* L) { diff --git a/rts/Lua/LuaUnsyncedRead.cpp b/rts/Lua/LuaUnsyncedRead.cpp index 4c9c2d4a9f..1d668bbc00 100644 --- a/rts/Lua/LuaUnsyncedRead.cpp +++ b/rts/Lua/LuaUnsyncedRead.cpp @@ -91,7 +91,6 @@ /****************************************************************************** * Callouts to get state * - * @module UnsyncedRead * @see rts/Lua/LuaUnsyncedRead.cpp ******************************************************************************/ @@ -466,7 +465,7 @@ static size_t PushSparseUnitTallyByDef(lua_State *const L, const T &v) * * @function Spring.IsReplay * - * @treturn ?nil|bool isReplay + * @return boolean? isReplay */ int LuaUnsyncedRead::IsReplay(lua_State* L) { @@ -479,7 +478,7 @@ int LuaUnsyncedRead::IsReplay(lua_State* L) * * @function Spring.GetReplayLength * - * @treturn ?nil|number timeInSeconds + * @return number? timeInSeconds */ int LuaUnsyncedRead::GetReplayLength(lua_State* L) { @@ -499,7 +498,7 @@ int LuaUnsyncedRead::GetReplayLength(lua_State* L) * * @function Spring.GetGameName * - * @treturn string name + * @return string name */ int LuaUnsyncedRead::GetGameName(lua_State* L) { @@ -511,7 +510,7 @@ int LuaUnsyncedRead::GetGameName(lua_State* L) * * @function Spring.GetMenuName * - * @treturn string name name .. version from Modinfo.lua. E.g. "Spring: 1944 test-5640-ac2d15b". + * @return string name name .. version from Modinfo.lua. E.g. "Spring: 1944 test-5640-ac2d15b". */ int LuaUnsyncedRead::GetMenuName(lua_State* L) { @@ -530,15 +529,15 @@ int LuaUnsyncedRead::GetMenuName(lua_State* L) * * @function Spring.GetProfilerTimeRecord * - * @string profilerName - * @bool[opt=false] frameData + * @param profilerName string + * @param frameData boolean? (Default: false) * - * @treturn number total in ms - * @treturn number current in ms - * @treturn number max_dt - * @treturn number time_pct - * @treturn number peak_pct - * @treturn ?nil|{[number]=number,...} frameData where key is the frame index and value is duration + * @return number total in ms + * @return number current in ms + * @return number max_dt + * @return number time_pct + * @return number peak_pct + * @return table? frameData Table where key is the frame index and value is duration. */ int LuaUnsyncedRead::GetProfilerTimeRecord(lua_State* L) { @@ -567,7 +566,7 @@ int LuaUnsyncedRead::GetProfilerTimeRecord(lua_State* L) * * @function Spring.GetProfilerRecordNames * - * @treturn {string,...} profilerNames + * @return string[] profilerNames */ int LuaUnsyncedRead::GetProfilerRecordNames(lua_State* L) { @@ -589,14 +588,14 @@ int LuaUnsyncedRead::GetProfilerRecordNames(lua_State* L) * * @function Spring.GetLuaMemUsage * - * @treturn number luaHandleAllocedMem in kilobytes - * @treturn number luaHandleNumAllocs divided by 1000 - * @treturn number luaGlobalAllocedMem in kilobytes - * @treturn number luaGlobalNumAllocs divided by 1000 - * @treturn number luaUnsyncedGlobalAllocedMem in kilobytes - * @treturn number luaUnsyncedGlobalNumAllocs divided by 1000 - * @treturn number luaSyncedGlobalAllocedMem in kilobytes - * @treturn number luaSyncedGlobalNumAllocs divided by 1000 + * @return number luaHandleAllocedMem in kilobytes + * @return number luaHandleNumAllocs divided by 1000 + * @return number luaGlobalAllocedMem in kilobytes + * @return number luaGlobalNumAllocs divided by 1000 + * @return number luaUnsyncedGlobalAllocedMem in kilobytes + * @return number luaUnsyncedGlobalNumAllocs divided by 1000 + * @return number luaSyncedGlobalAllocedMem in kilobytes + * @return number luaSyncedGlobalNumAllocs divided by 1000 */ int LuaUnsyncedRead::GetLuaMemUsage(lua_State* L) { @@ -640,8 +639,8 @@ int LuaUnsyncedRead::GetLuaMemUsage(lua_State* L) * * @function Spring.GetVidMemUsage * - * @treturn number usedMem in MB - * @treturn number availableMem in MB + * @return number usedMem in MB + * @return number availableMem in MB */ int LuaUnsyncedRead::GetVidMemUsage(lua_State* L) { @@ -690,15 +689,10 @@ static void PushTimer(lua_State* L, const spring_time& time, bool microseconds) lua_pushlightuserdata(L, reinterpret_cast(p)); } -/*** - * @type Timer - */ - - /*** Get a timer with millisecond resolution * * @function Spring.GetTimer - * @treturn Timer + * @return integer */ int LuaUnsyncedRead::GetTimer(lua_State* L) { @@ -710,7 +704,7 @@ int LuaUnsyncedRead::GetTimer(lua_State* L) /*** Get a timer with microsecond resolution * * @function Spring.GetTimerMicros - * @treturn Timer + * @return integer */ int LuaUnsyncedRead::GetTimerMicros(lua_State* L) { @@ -725,8 +719,8 @@ int LuaUnsyncedRead::GetTimerMicros(lua_State* L) * * This should give better results for camera interpolations * - * @bool[opt=false] lastFrameTime whether to use last frame time instead of last frame start - * @treturn Timer + * @param lastFrameTime boolean? (Default: false) whether to use last frame time instead of last frame start + * @return integer */ int LuaUnsyncedRead::GetFrameTimer(lua_State* L) { @@ -742,11 +736,11 @@ int LuaUnsyncedRead::GetFrameTimer(lua_State* L) /*** * * @function Spring.DiffTimers - * @tparam Timer endTimer - * @tparam Timer startTimer - * @bool[opt=false] returnMs whether to return `timeAmount` in milliseconds as opposed to seconds - * @bool[opt=false] fromMicroSecs whether timers are in microseconds instead of milliseconds - * @treturn number timeAmount + * @param endTimer integer + * @param startTimer integer + * @param returnMs boolean? (Default: false) whether to return `timeAmount` in milliseconds as opposed to seconds + * @param fromMicroSecs boolean? (Default: false) whether timers are in microseconds instead of milliseconds + * @return number timeAmount */ int LuaUnsyncedRead::DiffTimers(lua_State* L) { @@ -801,7 +795,7 @@ int LuaUnsyncedRead::DiffTimers(lua_State* L) * * @function Spring.GetNumDisplays * - * @treturn number numDisplays as returned by `SDL_GetNumVideoDisplays` + * @return number numDisplays as returned by `SDL_GetNumVideoDisplays` */ int LuaUnsyncedRead::GetNumDisplays(lua_State* L) { @@ -814,10 +808,10 @@ int LuaUnsyncedRead::GetNumDisplays(lua_State* L) * * @function Spring.GetViewGeometry * - * @treturn number viewSizeX in px - * @treturn number viewSizeY in px - * @treturn number viewPosX offset from leftmost screen left border in px - * @treturn number viewPosY offset from bottommost screen bottom border in px + * @return number viewSizeX in px + * @return number viewSizeY in px + * @return number viewPosX offset from leftmost screen left border in px + * @return number viewPosY offset from bottommost screen bottom border in px */ int LuaUnsyncedRead::GetViewGeometry(lua_State* L) { @@ -833,10 +827,10 @@ int LuaUnsyncedRead::GetViewGeometry(lua_State* L) * * @function Spring.GetDualViewGeometry * - * @treturn number dualViewSizeX in px - * @treturn number dualViewSizeY in px - * @treturn number dualViewPosX offset from leftmost screen left border in px - * @treturn number dualViewPosY offset from bottommost screen bottom border in px + * @return number dualViewSizeX in px + * @return number dualViewSizeY in px + * @return number dualViewPosX offset from leftmost screen left border in px + * @return number dualViewPosY offset from bottommost screen bottom border in px */ int LuaUnsyncedRead::GetDualViewGeometry(lua_State* L) { @@ -852,14 +846,14 @@ int LuaUnsyncedRead::GetDualViewGeometry(lua_State* L) * * @function Spring.GetWindowGeometry * - * @treturn number winSizeX in px - * @treturn number winSizeY in px - * @treturn number winPosX in px - * @treturn number winPosY in px - * @treturn number windowBorderTop in px - * @treturn number windowBorderLeft in px - * @treturn number windowBorderBottom in px - * @treturn number windowBorderRight in px + * @return number winSizeX in px + * @return number winSizeY in px + * @return number winPosX in px + * @return number winPosY in px + * @return number windowBorderTop in px + * @return number windowBorderLeft in px + * @return number windowBorderBottom in px + * @return number windowBorderRight in px */ int LuaUnsyncedRead::GetWindowGeometry(lua_State* L) { @@ -881,10 +875,10 @@ int LuaUnsyncedRead::GetWindowGeometry(lua_State* L) /*** Get main window display mode * * @function Spring.GetWindowDisplayMode - * @treturn number width in px - * @treturn number height in px - * @treturn number bits per pixel - * @treturn number refresh rate in Hz + * @return number width in px + * @return number height in px + * @return number bits per pixel + * @return number refresh rate in Hz */ int LuaUnsyncedRead::GetWindowDisplayMode(lua_State* L) { @@ -905,21 +899,21 @@ int LuaUnsyncedRead::GetWindowDisplayMode(lua_State* L) * * @function Spring.GetScreenGeometry * - * @number[opt=-1] displayIndex - * @bool[opt=false] queryUsable - * - * @treturn number screenSizeX in px - * @treturn number screenSizeY in px - * @treturn number screenPosX in px - * @treturn number screenPosY in px - * @treturn number windowBorderTop in px - * @treturn number windowBorderLeft in px - * @treturn number windowBorderBottom in px - * @treturn number windowBorderRight in px - * @treturn ?nil|number screenUsableSizeX in px - * @treturn ?nil|number screenUsableSizeY in px - * @treturn ?nil|number screenUsablePosX in px - * @treturn ?nil|number screenUsablePosY in px + * @param displayIndex number? (Default: -1) + * @param queryUsable boolean? (Default: false) + * + * @return number screenSizeX in px + * @return number screenSizeY in px + * @return number screenPosX in px + * @return number screenPosY in px + * @return number windowBorderTop in px + * @return number windowBorderLeft in px + * @return number windowBorderBottom in px + * @return number windowBorderRight in px + * @return number? screenUsableSizeX in px + * @return number? screenUsableSizeY in px + * @return number? screenUsablePosX in px + * @return number? screenUsablePosY in px */ int LuaUnsyncedRead::GetScreenGeometry(lua_State* L) { @@ -962,12 +956,12 @@ int LuaUnsyncedRead::GetScreenGeometry(lua_State* L) * * @function Spring.GetMiniMapGeometry * - * @treturn number minimapPosX in px - * @treturn number minimapPosY in px - * @treturn number minimapSizeX in px - * @treturn number minimapSizeY in px - * @treturn bool minimized - * @treturn bool maximized + * @return number minimapPosX in px + * @return number minimapPosY in px + * @return number minimapSizeX in px + * @return number minimapSizeY in px + * @return boolean minimized + * @return boolean maximized */ int LuaUnsyncedRead::GetMiniMapGeometry(lua_State* L) { @@ -988,7 +982,7 @@ int LuaUnsyncedRead::GetMiniMapGeometry(lua_State* L) /*** Get minimap rotation * * @function Spring.GetMiniMapRotation - * @treturn number amount in radians + * @return number amount in radians */ int LuaUnsyncedRead::GetMiniMapRotation(lua_State* L) { @@ -1004,7 +998,7 @@ int LuaUnsyncedRead::GetMiniMapRotation(lua_State* L) /*** * * @function Spring.GetMiniMapDualScreen - * @treturn string|false position "left"|"right" when dual screen is enabled, false when not + * @return string|false position "left"|"right" when dual screen is enabled, false when not */ int LuaUnsyncedRead::GetMiniMapDualScreen(lua_State* L) { @@ -1030,10 +1024,10 @@ int LuaUnsyncedRead::GetMiniMapDualScreen(lua_State* L) * * Returns nil when selection box is inactive * - * @treturn ?nil|number left - * @treturn ?nil|number top - * @treturn ?nil|number right - * @treturn ?nil|number bottom + * @return number? left + * @return number? top + * @return number? right + * @return number? bottom * * @see Spring.GetUnitsInScreenRectangle */ @@ -1061,7 +1055,7 @@ int LuaUnsyncedRead::GetSelectionBox(lua_State* L) /*** * * @function Spring.GetDrawSelectionInfo - * @treturn bool + * @return boolean */ int LuaUnsyncedRead::GetDrawSelectionInfo(lua_State* L) { @@ -1074,10 +1068,10 @@ int LuaUnsyncedRead::GetDrawSelectionInfo(lua_State* L) * * @function Spring.IsAboveMiniMap * - * @number x - * @number y + * @param x number + * @param y number * - * @treturn bool isAbove + * @return boolean isAbove */ int LuaUnsyncedRead::IsAboveMiniMap(lua_State* L) { @@ -1106,8 +1100,8 @@ int LuaUnsyncedRead::IsAboveMiniMap(lua_State* L) * * @function Spring.GetDrawFrame * - * @treturn number low_16bit - * @treturn number high_16bit + * @return number low_16bit + * @return number high_16bit */ int LuaUnsyncedRead::GetDrawFrame(lua_State* L) { @@ -1127,7 +1121,7 @@ int LuaUnsyncedRead::GetDrawFrame(lua_State* L) * When draw frames are not integer multiples of sim frames, some interpolation * happens, and this timeoffset shows how far along it is. * - * @treturn nil|number offset of the current draw frame from the last sim frame, expressed in fractions of a frame + * @return number? offset of the current draw frame from the last sim frame, expressed in fractions of a frame */ int LuaUnsyncedRead::GetFrameTimeOffset(lua_State* L) { @@ -1139,7 +1133,7 @@ int LuaUnsyncedRead::GetFrameTimeOffset(lua_State* L) * * Returns the game time, taking the interpolated draw frame into account. * - * @treturn number game time in seconds + * @return number game time in seconds */ int LuaUnsyncedRead::GetGameSecondsInterpolated(lua_State* L) { @@ -1151,7 +1145,7 @@ int LuaUnsyncedRead::GetGameSecondsInterpolated(lua_State* L) * * @function Spring.GetLastUpdateSeconds * - * @treturn nil|number lastUpdateSeconds + * @return number? lastUpdateSeconds */ int LuaUnsyncedRead::GetLastUpdateSeconds(lua_State* L) { @@ -1164,7 +1158,7 @@ int LuaUnsyncedRead::GetLastUpdateSeconds(lua_State* L) * * @function Spring.GetVideoCapturingMode * - * @treturn bool allowRecord + * @return boolean allowRecord */ int LuaUnsyncedRead::GetVideoCapturingMode(lua_State* L) { @@ -1182,8 +1176,8 @@ int LuaUnsyncedRead::GetVideoCapturingMode(lua_State* L) /*** * * @function Spring.IsUnitAllied - * @number unitID - * @treturn nil|bool isAllied nil with unitID cannot be parsed + * @param unitID integer + * @return boolean? isAllied nil with unitID cannot be parsed */ int LuaUnsyncedRead::IsUnitAllied(lua_State* L) { @@ -1206,8 +1200,8 @@ int LuaUnsyncedRead::IsUnitAllied(lua_State* L) /*** * * @function Spring.IsUnitSelected - * @number unitID - * @treturn nil|bool isSelected nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? isSelected nil when unitID cannot be parsed */ int LuaUnsyncedRead::IsUnitSelected(lua_State* L) { @@ -1224,8 +1218,8 @@ int LuaUnsyncedRead::IsUnitSelected(lua_State* L) /*** * * @function Spring.GetUnitLuaDraw - * @number unitID - * @treturn nil|bool draw nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? draw nil when unitID cannot be parsed */ int LuaUnsyncedRead::GetUnitLuaDraw(lua_State* L) { @@ -1235,8 +1229,8 @@ int LuaUnsyncedRead::GetUnitLuaDraw(lua_State* L) /*** * * @function Spring.GetUnitNoDraw - * @number unitID - * @treturn nil|bool nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? nil when unitID cannot be parsed */ int LuaUnsyncedRead::GetUnitNoDraw(lua_State* L) { @@ -1246,8 +1240,8 @@ int LuaUnsyncedRead::GetUnitNoDraw(lua_State* L) /*** * * @function Spring.GetUnitEngineDrawMask - * @number unitID - * @treturn nil|bool nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? nil when unitID cannot be parsed */ int LuaUnsyncedRead::GetUnitEngineDrawMask(lua_State* L) { @@ -1257,8 +1251,8 @@ int LuaUnsyncedRead::GetUnitEngineDrawMask(lua_State* L) /*** * * @function Spring.GetUnitAlwaysUpdateMatrix - * @number unitID - * @treturn nil|bool nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? nil when unitID cannot be parsed */ int LuaUnsyncedRead::GetUnitAlwaysUpdateMatrix(lua_State* L) { @@ -1274,8 +1268,8 @@ int LuaUnsyncedRead::GetUnitAlwaysUpdateMatrix(lua_State* L) /*** * * @function Spring.GetUnitDrawFlag - * @number unitID - * @treturn nil|number nil when unitID cannot be parsed + * @param unitID integer + * @return number? nil when unitID cannot be parsed */ int LuaUnsyncedRead::GetUnitDrawFlag(lua_State* L) { @@ -1291,8 +1285,8 @@ int LuaUnsyncedRead::GetUnitDrawFlag(lua_State* L) /*** * * @function Spring.GetUnitNoMinimap - * @number unitID - * @treturn nil|bool nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? nil when unitID cannot be parsed */ int LuaUnsyncedRead::GetUnitNoMinimap(lua_State* L) { @@ -1308,8 +1302,8 @@ int LuaUnsyncedRead::GetUnitNoMinimap(lua_State* L) /*** * * @function Spring.GetUnitNoGroup - * @number unitID - * @treturn nil|bool nil when unitID cannot be parsed + * @param unitID integer + * @return nil|bool noGroup `nil` when `unitID` cannot be parsed. */ int LuaUnsyncedRead::GetUnitNoGroup(lua_State* L) { @@ -1325,8 +1319,8 @@ int LuaUnsyncedRead::GetUnitNoGroup(lua_State* L) /*** * * @function Spring.GetUnitNoSelect - * @number unitID - * @treturn nil|bool nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? noSelect `nil` when `unitID` cannot be parsed. */ int LuaUnsyncedRead::GetUnitNoSelect(lua_State* L) { @@ -1343,8 +1337,9 @@ int LuaUnsyncedRead::GetUnitNoSelect(lua_State* L) /*** * * @function Spring.UnitIconGetDraw - * @number unitID - * @tparam nil|bool nil when unitID is invalid + * @param unitID integer + * @return boolean? drawIcon + * `true` if icon is being drawn, `nil` when unitID is invalid, otherwise `false`. */ int LuaUnsyncedRead::UnitIconGetDraw(lua_State* L) { CUnit* unit = ParseUnit(L, __func__, 1); @@ -1360,17 +1355,17 @@ int LuaUnsyncedRead::UnitIconGetDraw(lua_State* L) { /*** * * @function Spring.GetUnitSelectionVolumeData - * @number unitID - * @treturn number|nil scaleX nil when unitID cannot be parsed - * @treturn number scaleY - * @treturn number scaleZ - * @treturn number offsetX - * @treturn number offsetY - * @treturn number offsetZ - * @treturn number volumeType - * @treturn number useContHitTest - * @treturn number getPrimaryAxis - * @treturn bool ignoreHits + * @param unitID integer + * @return number? scaleX nil when unitID cannot be parsed + * @return number scaleY + * @return number scaleZ + * @return number offsetX + * @return number offsetY + * @return number offsetZ + * @return number volumeType + * @return number useContHitTest + * @return number getPrimaryAxis + * @return boolean ignoreHits */ int LuaUnsyncedRead::GetUnitSelectionVolumeData(lua_State* L) { @@ -1387,8 +1382,8 @@ int LuaUnsyncedRead::GetUnitSelectionVolumeData(lua_State* L) /*** * * @function Spring.GetFeatureLuaDraw - * @number featureID - * @treturn nil|bool nil when featureID cannot be parsed + * @param featureID integer + * @return boolean? nil when featureID cannot be parsed */ int LuaUnsyncedRead::GetFeatureLuaDraw(lua_State* L) { @@ -1398,8 +1393,8 @@ int LuaUnsyncedRead::GetFeatureLuaDraw(lua_State* L) /*** * * @function Spring.GetFeatureNoDraw - * @number featureID - * @treturn nil|bool nil when featureID cannot be parsed + * @param featureID integer + * @return boolean? nil when featureID cannot be parsed */ int LuaUnsyncedRead::GetFeatureNoDraw(lua_State* L) { @@ -1409,8 +1404,8 @@ int LuaUnsyncedRead::GetFeatureNoDraw(lua_State* L) /*** * * @function Spring.GetFeatureEngineDrawMask - * @number featureID - * @treturn nil|bool nil when featureID cannot be parsed + * @param featureID integer + * @return boolean? nil when featureID cannot be parsed */ int LuaUnsyncedRead::GetFeatureEngineDrawMask(lua_State* L) { @@ -1420,8 +1415,8 @@ int LuaUnsyncedRead::GetFeatureEngineDrawMask(lua_State* L) /*** * * @function Spring.GetFeatureAlwaysUpdateMatrix - * @number featureID - * @treturn nil|bool nil when featureID cannot be parsed + * @param featureID integer + * @return boolean? nil when featureID cannot be parsed */ int LuaUnsyncedRead::GetFeatureAlwaysUpdateMatrix(lua_State* L) { @@ -1437,8 +1432,8 @@ int LuaUnsyncedRead::GetFeatureAlwaysUpdateMatrix(lua_State* L) /*** * * @function Spring.GetFeatureDrawFlag - * @number featureID - * @treturn nil|number nil when featureID cannot be parsed + * @param featureID integer + * @return number? nil when featureID cannot be parsed */ int LuaUnsyncedRead::GetFeatureDrawFlag(lua_State* L) { @@ -1454,17 +1449,17 @@ int LuaUnsyncedRead::GetFeatureDrawFlag(lua_State* L) /*** * * @function Spring.GetFeatureSelectionVolumeData - * @number featureID - * @treturn number|nil scaleX nil when unitID cannot be parsed - * @treturn number scaleY - * @treturn number scaleZ - * @treturn number offsetX - * @treturn number offsetY - * @treturn number offsetZ - * @treturn number volumeType - * @treturn number useContHitTest - * @treturn number getPrimaryAxis - * @treturn bool ignoreHits + * @param featureID integer + * @return number? scaleX nil when unitID cannot be parsed + * @return number scaleY + * @return number scaleZ + * @return number offsetX + * @return number offsetY + * @return number offsetZ + * @return number volumeType + * @return number useContHitTest + * @return number getPrimaryAxis + * @return boolean ignoreHits */ int LuaUnsyncedRead::GetFeatureSelectionVolumeData(lua_State* L) { @@ -1503,23 +1498,23 @@ static int GetObjectTransformMatrix(const CSolidObject* o, lua_State* L) /*** * * @function Spring.GetUnitTransformMatrix - * @number unitID - * @treturn number|nil m11 nil when unitID cannot be parsed - * @treturn number m12 - * @treturn number m13 - * @treturn number m14 - * @treturn number m21 - * @treturn number m22 - * @treturn number m23 - * @treturn number m24 - * @treturn number m31 - * @treturn number m32 - * @treturn number m33 - * @treturn number m34 - * @treturn number m41 - * @treturn number m42 - * @treturn number m43 - * @treturn number m44 + * @param unitID integer + * @return number? m11 nil when unitID cannot be parsed + * @return number m12 + * @return number m13 + * @return number m14 + * @return number m21 + * @return number m22 + * @return number m23 + * @return number m24 + * @return number m31 + * @return number m32 + * @return number m33 + * @return number m34 + * @return number m41 + * @return number m42 + * @return number m43 + * @return number m44 */ int LuaUnsyncedRead::GetUnitTransformMatrix(lua_State* L) { return (GetObjectTransformMatrix(ParseUnit(L, __func__, 1), L)); } @@ -1527,23 +1522,23 @@ int LuaUnsyncedRead::GetUnitTransformMatrix(lua_State* L) { return (GetObjectTra /*** * * @function Spring.GetFeatureTransformMatrix - * @number featureID - * @treturn number|nil m11 nil when featureID cannot be parsed - * @treturn number m12 - * @treturn number m13 - * @treturn number m14 - * @treturn number m21 - * @treturn number m22 - * @treturn number m23 - * @treturn number m24 - * @treturn number m31 - * @treturn number m32 - * @treturn number m33 - * @treturn number m34 - * @treturn number m41 - * @treturn number m42 - * @treturn number m43 - * @treturn number m44 + * @param featureID integer + * @return number? m11 nil when featureID cannot be parsed + * @return number m12 + * @return number m13 + * @return number m14 + * @return number m21 + * @return number m22 + * @return number m23 + * @return number m24 + * @return number m31 + * @return number m32 + * @return number m33 + * @return number m34 + * @return number m41 + * @return number m42 + * @return number m43 + * @return number m44 */ int LuaUnsyncedRead::GetFeatureTransformMatrix(lua_State* L) { return (GetObjectTransformMatrix(ParseFeature(L, __func__, 1), L)); } @@ -1557,8 +1552,8 @@ int LuaUnsyncedRead::GetFeatureTransformMatrix(lua_State* L) { return (GetObject /*** * * @function Spring.IsUnitInView - * @number unitID - * @treturn nil|bool inView nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? inView nil when unitID cannot be parsed */ int LuaUnsyncedRead::IsUnitInView(lua_State* L) { @@ -1575,10 +1570,10 @@ int LuaUnsyncedRead::IsUnitInView(lua_State* L) /*** * * @function Spring.IsUnitVisible - * @number unitID - * @number[opt] radius unitRadius when not specified - * @bool checkIcon - * @treturn nil|bool isVisible nil when unitID cannot be parsed + * @param unitID integer + * @param radius number? unitRadius when not specified + * @param checkIcon boolean + * @return boolean? isVisible nil when unitID cannot be parsed */ int LuaUnsyncedRead::IsUnitVisible(lua_State* L) { @@ -1617,8 +1612,8 @@ int LuaUnsyncedRead::IsUnitVisible(lua_State* L) /*** * * @function Spring.IsUnitIcon - * @number unitID - * @treturn nil|bool isUnitIcon nil when unitID cannot be parsed + * @param unitID integer + * @return boolean? isUnitIcon nil when unitID cannot be parsed */ int LuaUnsyncedRead::IsUnitIcon(lua_State* L) { @@ -1635,13 +1630,13 @@ int LuaUnsyncedRead::IsUnitIcon(lua_State* L) /*** * * @function Spring.IsAABBInView - * @number minX - * @number minY - * @number minZ - * @number maxX - * @number maxY - * @number maxZ - * @treturn bool inView + * @param minX number + * @param minY number + * @param minZ number + * @param maxX number + * @param maxY number + * @param maxZ number + * @return boolean inView */ int LuaUnsyncedRead::IsAABBInView(lua_State* L) { @@ -1664,11 +1659,11 @@ int LuaUnsyncedRead::IsAABBInView(lua_State* L) /*** * * @function Spring.IsSphereInView - * @number posX - * @number posY - * @number posZ - * @number[opt=0] radius - * @treturn bool inView + * @param posX number + * @param posY number + * @param posZ number + * @param radius number? (Default: 0) + * @return boolean inView */ int LuaUnsyncedRead::IsSphereInView(lua_State* L) { @@ -1685,11 +1680,11 @@ int LuaUnsyncedRead::IsSphereInView(lua_State* L) /*** * * @function Spring.GetUnitViewPosition - * @number unitID - * @bool[opt=false] midPos - * @treturn number|nil x nil when unitID cannot be parsed - * @treturn number y - * @treturn number z + * @param unitID integer + * @param midPos boolean? (Default: false) + * @return number? x nil when unitID cannot be parsed + * @return number y + * @return number z */ int LuaUnsyncedRead::GetUnitViewPosition(lua_State* L) { @@ -1780,10 +1775,10 @@ class CVisProjectileQuadDrawer: public CWorldObjectQuadDrawer { /*** * * @function Spring.GetVisibleUnits - * @number[opt=-1] teamID - * @number[opt=30] radius - * @bool[opt=true] icons - * @treturn nil|{[number],...} unitIDs + * @param teamID integer? (Default: -1) + * @param radius number? (Default: 30) + * @param icons boolean? (Default: true) + * @return nil|number[] unitIDs */ int LuaUnsyncedRead::GetVisibleUnits(lua_State* L) { @@ -1878,11 +1873,11 @@ int LuaUnsyncedRead::GetVisibleUnits(lua_State* L) /*** * * @function Spring.GetVisibleFeatures - * @number[opt=-1] teamID - * @number[opt=30] radius - * @bool[opt=true] icons - * @bool[opt=true] geos - * @treturn nil|{[number],...} featureIDs + * @param teamID integer? (Default: -1) + * @param radius number? (Default: 30) + * @param icons boolean? (Default: true) + * @param geos boolean? (Default: true) + * @return nil|number[] featureIDs */ int LuaUnsyncedRead::GetVisibleFeatures(lua_State* L) { @@ -1959,11 +1954,11 @@ int LuaUnsyncedRead::GetVisibleFeatures(lua_State* L) /*** * * @function Spring.GetVisibleProjectiles - * @number[opt=-1] allyTeamID - * @bool[opt=true] addSyncedProjectiles - * @bool[opt=true] addWeaponProjectiles - * @bool[opt=true] addPieceProjectiles - * @treturn nil|{[number],...} projectileIDs + * @param allyTeamID integer? (Default: -1) + * @param addSyncedProjectiles boolean? (Default: true) + * @param addWeaponProjectiles boolean? (Default: true) + * @param addPieceProjectiles boolean? (Default: true) + * @return nil|number[] projectileIDs */ int LuaUnsyncedRead::GetVisibleProjectiles(lua_State* L) { @@ -2149,7 +2144,7 @@ int LuaUnsyncedRead::GetRenderFeaturesDrawFlagChanged(lua_State* L) /*** * * @function Spring.ClearUnitsPreviousDrawFlag - * @treturn nil + * @return nil */ int LuaUnsyncedRead::ClearUnitsPreviousDrawFlag(lua_State* L) { @@ -2160,7 +2155,7 @@ int LuaUnsyncedRead::ClearUnitsPreviousDrawFlag(lua_State* L) /*** * * @function Spring.ClearFeaturesPreviousDrawFlag - * @treturn nil + * @return nil */ int LuaUnsyncedRead::ClearFeaturesPreviousDrawFlag(lua_State* L) { @@ -2171,12 +2166,12 @@ int LuaUnsyncedRead::ClearFeaturesPreviousDrawFlag(lua_State* L) /*** Get units inside a rectangle area on the map * * @function Spring.GetUnitsInScreenRectangle - * @number left - * @number top - * @number right - * @number bottom - * @number[opt=-1] allegiance teamID when > 0, when < 0 one of AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4 - * @treturn nil|{[number],...} unitIDs + * @param left number + * @param top number + * @param right number + * @param bottom number + * @param allegiance number? (Default: -1) teamID when > 0, when < 0 one of AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4 + * @return nil|number[] unitIDs */ int LuaUnsyncedRead::GetUnitsInScreenRectangle(lua_State* L) { @@ -2270,11 +2265,11 @@ int LuaUnsyncedRead::GetUnitsInScreenRectangle(lua_State* L) /*** Get features inside a rectangle area on the map * * @function Spring.GetFeaturesInScreenRectangle - * @number left - * @number top - * @number right - * @number bottom - * @treturn nil|{[number],...} featureIDs + * @param left number + * @param top number + * @param right number + * @param bottom number + * @return nil|number[] featureIDs */ int LuaUnsyncedRead::GetFeaturesInScreenRectangle(lua_State* L) { @@ -2326,7 +2321,7 @@ int LuaUnsyncedRead::GetFeaturesInScreenRectangle(lua_State* L) /*** * * @function Spring.GetLocalPlayerID - * @treturn number playerID + * @return number playerID */ int LuaUnsyncedRead::GetLocalPlayerID(lua_State* L) { @@ -2338,7 +2333,7 @@ int LuaUnsyncedRead::GetLocalPlayerID(lua_State* L) /*** * * @function Spring.GetLocalTeamID - * @treturn number teamID + * @return number teamID */ int LuaUnsyncedRead::GetLocalTeamID(lua_State* L) { @@ -2350,7 +2345,7 @@ int LuaUnsyncedRead::GetLocalTeamID(lua_State* L) /*** * * @function Spring.GetLocalAllyTeamID - * @treturn number allyTeamID + * @return number allyTeamID */ int LuaUnsyncedRead::GetLocalAllyTeamID(lua_State* L) { @@ -2362,9 +2357,9 @@ int LuaUnsyncedRead::GetLocalAllyTeamID(lua_State* L) /*** * * @function Spring.GetSpectatingState - * @treturn bool spectating - * @treturn bool spectatingFullView - * @treturn bool spectatingFullSelect + * @return boolean spectating + * @return boolean spectatingFullView + * @return boolean spectatingFullSelect */ int LuaUnsyncedRead::GetSpectatingState(lua_State* L) { @@ -2381,7 +2376,7 @@ int LuaUnsyncedRead::GetSpectatingState(lua_State* L) /*** * * @function Spring.GetSelectedUnits - * @treturn {[number],...} unitIDs + * @return number[] unitIDs */ int LuaUnsyncedRead::GetSelectedUnits(lua_State* L) { @@ -2392,8 +2387,8 @@ int LuaUnsyncedRead::GetSelectedUnits(lua_State* L) /*** Get selected units aggregated by unitDefID * * @function Spring.GetSelectedUnitsSorted - * @treturn {[number]={number,...},...} where keys are unitDefIDs and values are unitIDs - * @treturn n the number of unitDefIDs + * @return table where keys are unitDefIDs and values are unitIDs + * @return integer the number of unitDefIDs */ int LuaUnsyncedRead::GetSelectedUnitsSorted(lua_State* L) { @@ -2408,8 +2403,8 @@ int LuaUnsyncedRead::GetSelectedUnitsSorted(lua_State* L) * * @function Spring.GetSelectedUnitsCounts * - * @treturn {[number]=number,...} unitsCounts where keys are unitDefIDs and values are counts - * @treturn n the number of unitDefIDs + * @return table unitsCounts where keys are unitDefIDs and values are counts + * @return integer the number of unitDefIDs */ int LuaUnsyncedRead::GetSelectedUnitsCounts(lua_State* L) { @@ -2423,7 +2418,7 @@ int LuaUnsyncedRead::GetSelectedUnitsCounts(lua_State* L) /*** Returns the amount of selected units * * @function Spring.GetSelectedUnitsCount - * @treturn number selectedUnitsCount + * @return number selectedUnitsCount */ int LuaUnsyncedRead::GetSelectedUnitsCount(lua_State* L) { @@ -2435,7 +2430,7 @@ int LuaUnsyncedRead::GetSelectedUnitsCount(lua_State* L) * * @function Spring.GetBoxSelectionByEngine * - * @treturn bool when true engine won't select units inside selection box when released + * @return boolean when true engine won't select units inside selection box when released * * @see Spring.GetSelectionBox * @see Spring.SetBoxSelectionByEngine @@ -2453,7 +2448,7 @@ int LuaUnsyncedRead::GetBoxSelectionByEngine(lua_State* L) /*** * * @function Spring.IsGUIHidden - * @treturn bool + * @return boolean */ int LuaUnsyncedRead::IsGUIHidden(lua_State* L) { @@ -2465,7 +2460,7 @@ int LuaUnsyncedRead::IsGUIHidden(lua_State* L) /*** * * @function Spring.HaveShadows - * @treturn shadowsLoaded + * @return boolean shadowsLoaded */ int LuaUnsyncedRead::HaveShadows(lua_State* L) { @@ -2477,8 +2472,8 @@ int LuaUnsyncedRead::HaveShadows(lua_State* L) /*** * * @function Spring.HaveAdvShading - * @treturn bool useAdvShading - * @treturn bool groundUseAdvShading + * @return boolean useAdvShading + * @return boolean groundUseAdvShading */ int LuaUnsyncedRead::HaveAdvShading(lua_State* L) { @@ -2491,8 +2486,8 @@ int LuaUnsyncedRead::HaveAdvShading(lua_State* L) /*** * * @function Spring.GetWaterMode - * @treturn number waterRendererID - * @treturn string waterRendererName + * @return number waterRendererID + * @return string waterRendererName * @see rts/Rendering/Env/IWater.h */ int LuaUnsyncedRead::GetWaterMode(lua_State* L) @@ -2507,7 +2502,7 @@ int LuaUnsyncedRead::GetWaterMode(lua_State* L) /*** * * @function Spring.GetMapDrawMode - * @treturn nil|string "normal"|"height"|"metal"|"pathTraversability"|"los" + * @return "normal"|"height"|"metal"|"pathTraversability"|"los" */ int LuaUnsyncedRead::GetMapDrawMode(lua_State* L) { @@ -2536,12 +2531,12 @@ int LuaUnsyncedRead::GetMapDrawMode(lua_State* L) /*** * * @function Spring.GetMapSquareTexture - * @number texSquareX - * @number texSquareY - * @number lodMin - * @string luaTexName - * @number[opt=lodMin] lodMax - * @treturn nil|bool success + * @param texSquareX number + * @param texSquareY number + * @param lodMin number + * @param luaTexName string + * @param lodMax number? (Default: lodMin) + * @return boolean? success */ int LuaUnsyncedRead::GetMapSquareTexture(lua_State* L) { @@ -2590,19 +2585,13 @@ int LuaUnsyncedRead::GetMapSquareTexture(lua_State* L) return 1; } - -/*** Color triple (RGB) - * @table rgb - * @number r - * @number g - * @number b - */ - - /*** - * * @function Spring.GetLosViewColors - * @treturn { always=rgb, LOS=rgb, radar=rgb, jam=rgb, radar2=rgb } + * @return rgb always + * @return rgb LOS + * @return rgb radar + * @return rgb jam + * @return rgb radar2 */ int LuaUnsyncedRead::GetLosViewColors(lua_State* L) { @@ -2627,12 +2616,12 @@ int LuaUnsyncedRead::GetLosViewColors(lua_State* L) /*** * * @function Spring.GetNanoProjectileParams - * @treturn number rotVal in degrees - * @treturn number rotVel in degrees - * @treturn number rotAcc in degrees - * @treturn number rotValRng in degrees - * @treturn number rotVelRng in degrees - * @treturn number rotAccRng in degrees + * @return number rotVal in degrees + * @return number rotVel in degrees + * @return number rotAcc in degrees + * @return number rotValRng in degrees + * @return number rotVelRng in degrees + * @return number rotAccRng in degrees */ int LuaUnsyncedRead::GetNanoProjectileParams(lua_State* L) { @@ -2648,10 +2637,11 @@ int LuaUnsyncedRead::GetNanoProjectileParams(lua_State* L) } -/*** Get available cameras +/*** + * Get available cameras. * * @function Spring.GetCameraNames - * @treturn {[string] = number} where keys are names and values are indices + * @return table Table where where keys are names and values are indices. */ int LuaUnsyncedRead::GetCameraNames(lua_State* L) { @@ -2668,40 +2658,16 @@ int LuaUnsyncedRead::GetCameraNames(lua_State* L) return 1; } - -/*** Parameters for camera state - * - * @table camState - * - * Highly dependent on the type of the current camera controller - * - * @string name "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy" - * @number mode the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy) - * @number fov - * @number px Position X of the ground point in screen center - * @number py Position Y of the ground point in screen center - * @number pz Position Z of the ground point in screen center - * @number dx Camera direction vector X - * @number dy Camera direction vector Y - * @number dz Camera direction vector Z - * @number rx Camera rotation angle on X axis (spring) - * @number ry Camera rotation angle on Y axis (spring) - * @number rz Camera rotation angle on Z axis (spring) - * @number angle Camera rotation angle on X axis (aka tilt/pitch) (ta) - * @number flipped -1 for when south is down, 1 for when north is down (ta) - * @number dist Camera distance from the ground (spring) - * @number height Camera distance from the ground (ta) - * @number oldHeight Camera distance from the ground, cannot be changed (rot) +/*** + * @function Spring.GetCameraState + * @param useReturns false + * @return CameraState cameraState */ - - /*** - * * @function Spring.GetCameraState - * @bool[opt=true] useReturns when true return multiple values instead of table - * @treturn any|camState ret1 - * @treturn any|nil ret2 - * @treturn any|nil retn + * @param useReturns true? (Default: `true`) Return multiple values instead of a table. + * @return "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy" name + * @return any Fields depending on current controller mode. */ int LuaUnsyncedRead::GetCameraState(lua_State* L) { @@ -2769,11 +2735,10 @@ int LuaUnsyncedRead::GetCameraState(lua_State* L) /*** - * * @function Spring.GetCameraPosition - * @treturn posX - * @treturn posY - * @treturn posZ + * @return number posX + * @return number posY + * @return number posZ */ int LuaUnsyncedRead::GetCameraPosition(lua_State* L) { @@ -2784,11 +2749,10 @@ int LuaUnsyncedRead::GetCameraPosition(lua_State* L) } /*** - * * @function Spring.GetCameraDirection - * @treturn dirX - * @treturn dirY - * @treturn dirZ + * @return number dirX + * @return number dirY + * @return number dirZ */ int LuaUnsyncedRead::GetCameraDirection(lua_State* L) { @@ -2799,11 +2763,10 @@ int LuaUnsyncedRead::GetCameraDirection(lua_State* L) } /*** - * * @function Spring.GetCameraRotation - * @treturn rotX in radians - * @treturn rotY in radians - * @treturn rotZ in radians + * @return number rotX in radians + * @return number rotY in radians + * @return number rotZ in radians */ int LuaUnsyncedRead::GetCameraRotation(lua_State* L) { @@ -2814,10 +2777,9 @@ int LuaUnsyncedRead::GetCameraRotation(lua_State* L) } /*** - * * @function Spring.GetCameraFOV - * @treturn number vFOV - * @treturn number hFOV + * @return number vFOV + * @return number hFOV */ int LuaUnsyncedRead::GetCameraFOV(lua_State* L) { @@ -2826,19 +2788,20 @@ int LuaUnsyncedRead::GetCameraFOV(lua_State* L) return 2; } - -/*** Cartesian triple (XYZ) - * @table xyz - * @number x - * @number y - * @number z +/** + * @class CameraVectors + * @field forward xyz + * @field up xyz + * @field right xyz + * @field topFrustumPlane xyz + * @field botFrustumPlane xyz + * @field lftFrustumPlane xyz + * @field rgtFrustumPlane xyz */ - /*** - * * @function Spring.GetCameraVectors - * @treturn { forward = xyz, up = xyz, right = xyz, topFrustumPlane = xyz, botFrustumPlane = xyz, lftFrustumPlane = xyz, rgtFrustumPlane = xyz } + * @return CameraVectors */ int LuaUnsyncedRead::GetCameraVectors(lua_State* L) { @@ -2866,12 +2829,12 @@ int LuaUnsyncedRead::GetCameraVectors(lua_State* L) /*** * * @function Spring.WorldToScreenCoords - * @number x - * @number y - * @number z - * @treturn viewPortX - * @treturn viewPortY - * @treturn viewPortZ + * @param x number + * @param y number + * @param z number + * @return number viewPortX + * @return number viewPortY + * @return number viewPortZ */ int LuaUnsyncedRead::WorldToScreenCoords(lua_State* L) { @@ -2898,17 +2861,17 @@ int LuaUnsyncedRead::WorldToScreenCoords(lua_State* L) * * The unit must be selectable, to appear to a screen trace ray. * - * @number screenX position on x axis in mouse coordinates (origin on left border of view) - * @number screenY position on y axis in mouse coordinates (origin on top border of view) - * @bool[opt=false] onlyCoords return only description (1st return value) and coordinates (2nd return value) - * @bool[opt=false] useMinimap if position arguments are contained by minimap, use the minimap corresponding world position - * @bool[opt=false] includeSky - * @bool[opt=false] ignoreWater - * @number[opt=0] heightOffset - * @treturn nil|string description of traced position - * @treturn nil|number|string|xyz unitID or feature, position triple when onlyCoords=true - * @treturn nil|number|string featureID or ground - * @treturn nil|xyz coords + * @param screenX number position on x axis in mouse coordinates (origin on left border of view) + * @param screenY number position on y axis in mouse coordinates (origin on top border of view) + * @param onlyCoords boolean? (Default: false) return only description (1st return value) and coordinates (2nd return value) + * @param useMinimap boolean? (Default: false) if position arguments are contained by minimap, use the minimap corresponding world position + * @param includeSky boolean? (Default: false) + * @param ignoreWater boolean? (Default: false) + * @param heightOffset number? (Default: 0) + * @return nil|string description of traced position + * @return nil|number|string|xyz unitID or feature, position triple when onlyCoords=true + * @return nil|number|string featureID or ground + * @return nil|xyz coords */ int LuaUnsyncedRead::TraceScreenRay(lua_State* L) { @@ -3015,11 +2978,11 @@ int LuaUnsyncedRead::TraceScreenRay(lua_State* L) /*** * * @function Spring.GetPixelDir - * @number x - * @number y - * @treturn dirX - * @treturn dirY - * @treturn dirZ + * @param x number + * @param y number + * @return number dirX + * @return number dirY + * @return number dirZ */ int LuaUnsyncedRead::GetPixelDir(lua_State* L) { @@ -3070,11 +3033,11 @@ static bool AddPlayerToRoster(lua_State* L, int playerID, bool onlyActivePlayers /*** * * @function Spring.GetTeamColor - * @number teamID - * @treturn nil|number r factor from 0 to 1 - * @treturn nil|number g factor from 0 to 1 - * @treturn nil|number b factor from 0 to 1 - * @treturn nil|number a factor from 0 to 1 + * @param teamID integer + * @return number? r factor from 0 to 1 + * @return number? g factor from 0 to 1 + * @return number? b factor from 0 to 1 + * @return number? a factor from 0 to 1 */ int LuaUnsyncedRead::GetTeamColor(lua_State* L) { @@ -3097,11 +3060,11 @@ int LuaUnsyncedRead::GetTeamColor(lua_State* L) /*** * * @function Spring.GetTeamOrigColor - * @number teamID - * @treturn nil|number r factor from 0 to 1 - * @treturn nil|number g factor from 0 to 1 - * @treturn nil|number b factor from 0 to 1 - * @treturn nil|number a factor from 0 to 1 + * @param teamID integer + * @return number? r factor from 0 to 1 + * @return number? g factor from 0 to 1 + * @return number? b factor from 0 to 1 + * @return number? a factor from 0 to 1 */ int LuaUnsyncedRead::GetTeamOrigColor(lua_State* L) { @@ -3124,7 +3087,7 @@ int LuaUnsyncedRead::GetTeamOrigColor(lua_State* L) /*** * * @function Spring.GetDrawSeconds - * @treturn time in seconds + * @return integer Time in seconds */ int LuaUnsyncedRead::GetDrawSeconds(lua_State* L) { @@ -3142,8 +3105,8 @@ int LuaUnsyncedRead::GetDrawSeconds(lua_State* L) /*** * * @function Spring.GetSoundStreamTime - * @treturn number playTime - * @treturn number time + * @return number playTime + * @return number time */ int LuaUnsyncedRead::GetSoundStreamTime(lua_State* L) { @@ -3246,7 +3209,7 @@ int LuaUnsyncedRead::GetSoundEffectParams(lua_State* L) /*** * * @function Spring.GetFPS - * @treturn number fps + * @return number fps */ int LuaUnsyncedRead::GetFPS(lua_State* L) { @@ -3260,9 +3223,9 @@ int LuaUnsyncedRead::GetFPS(lua_State* L) /*** * * @function Spring.GetGameSpeed - * @treturn number wantedSpeedFactor - * @treturn number speedFactor - * @treturn bool paused + * @return number wantedSpeedFactor + * @return number speedFactor + * @return boolean paused */ int LuaUnsyncedRead::GetGameSpeed(lua_State* L) { @@ -3275,11 +3238,11 @@ int LuaUnsyncedRead::GetGameSpeed(lua_State* L) /*** * * @function Spring.GetGameState - * @number[opt=500] maxLatency used for `isSimLagging` return parameter - * @treturn bool doneLoading - * @treturn bool isSavedGame - * @treturn bool isClientPaused - * @treturn bool isSimLagging + * @param maxLatency number? (Default: 500) used for `isSimLagging` return parameter + * @return boolean doneLoading + * @return boolean isSavedGame + * @return boolean isClientPaused + * @return boolean isSimLagging */ int LuaUnsyncedRead::GetGameState(lua_State* L) { @@ -3302,10 +3265,10 @@ int LuaUnsyncedRead::GetGameState(lua_State* L) /*** * * @function Spring.GetActiveCommand - * @treturn nil|number cmdIndex - * @treturn nil|number cmdID - * @treturn nil|number cmdType - * @treturn nil|string cmdName + * @return number? cmdIndex + * @return number? cmdID + * @return number? cmdType + * @return nil|string cmdName */ int LuaUnsyncedRead::GetActiveCommand(lua_State* L) { @@ -3331,10 +3294,10 @@ int LuaUnsyncedRead::GetActiveCommand(lua_State* L) /*** * * @function Spring.GetDefaultCommand - * @treturn nil|number cmdIndex - * @treturn nil|number cmdID - * @treturn nil|number cmdType - * @treturn nil|string cmdName + * @return number? cmdIndex + * @return number? cmdID + * @return number? cmdType + * @return nil|string cmdName */ int LuaUnsyncedRead::GetDefaultCommand(lua_State* L) { @@ -3357,33 +3320,10 @@ int LuaUnsyncedRead::GetDefaultCommand(lua_State* L) return 4; } - -/*** Command Description - * - * @table cmdDesc - * - * Contains data about a command - * - * @number id - * @number type - * @string name - * @string action - * @string tooltip - * @string texture - * @string cursor - * @bool queueing - * @bool hidden - * @bool disabled - * @bool showUnique - * @bool onlyTexture - * @tparam {[string],...} params - */ - - /*** * * @function Spring.GetActiveCmdDescs - * @treturn {[cmdDesc],...} cmdDescs + * @return CommandDescription[] cmdDescs */ int LuaUnsyncedRead::GetActiveCmdDescs(lua_State* L) { @@ -3412,8 +3352,8 @@ int LuaUnsyncedRead::GetActiveCmdDescs(lua_State* L) /*** * * @function Spring.GetActiveCmdDesc - * @number cmdIndex - * @treturn nil|cmdDesc + * @param cmdIndex integer + * @return CommandDescription? */ int LuaUnsyncedRead::GetActiveCmdDesc(lua_State* L) { @@ -3436,8 +3376,8 @@ int LuaUnsyncedRead::GetActiveCmdDesc(lua_State* L) /*** * * @function Spring.GetCmdDescIndex - * @number cmdID - * @treturn nil|number cmdDescIndex + * @param cmdID integer + * @return integer? cmdDescIndex */ int LuaUnsyncedRead::GetCmdDescIndex(lua_State* L) { @@ -3460,10 +3400,18 @@ int LuaUnsyncedRead::GetCmdDescIndex(lua_State* L) /******************************************************************************/ +/*** + * @alias Facing + * | 0 # South + * | 1 # East + * | 2 # North + * | 3 # West + */ + /*** * * @function Spring.GetBuildFacing - * @treturn number buildFacing + * @return Facing buildFacing */ int LuaUnsyncedRead::GetBuildFacing(lua_State* L) { @@ -3478,7 +3426,7 @@ int LuaUnsyncedRead::GetBuildFacing(lua_State* L) /*** * * @function Spring.GetBuildSpacing - * @treturn number buildSpacing + * @return number buildSpacing */ int LuaUnsyncedRead::GetBuildSpacing(lua_State* L) { @@ -3493,7 +3441,7 @@ int LuaUnsyncedRead::GetBuildSpacing(lua_State* L) /*** * * @function Spring.GetGatherMode - * @treturn number gatherMode + * @return number gatherMode */ int LuaUnsyncedRead::GetGatherMode(lua_State* L) { @@ -3510,8 +3458,8 @@ int LuaUnsyncedRead::GetGatherMode(lua_State* L) /*** * * @function Spring.GetActivePage - * @treturn number activePage - * @treturn number maxPage + * @return number activePage + * @return number maxPage */ int LuaUnsyncedRead::GetActivePage(lua_State* L) { @@ -3533,13 +3481,13 @@ int LuaUnsyncedRead::GetActivePage(lua_State* L) /*** * * @function Spring.GetMouseState - * @treturn number x - * @treturn number y - * @treturn number lmbPressed left mouse button pressed - * @treturn number mmbPressed middle mouse button pressed - * @treturn number rmbPressed right mouse button pressed - * @treturn bool offscreen - * @treturn bool mmbScroll + * @return number x + * @return number y + * @return number lmbPressed left mouse button pressed + * @return number mmbPressed middle mouse button pressed + * @return number rmbPressed right mouse button pressed + * @return boolean offscreen + * @return boolean mmbScroll */ int LuaUnsyncedRead::GetMouseState(lua_State* L) { @@ -3561,8 +3509,8 @@ int LuaUnsyncedRead::GetMouseState(lua_State* L) /*** * * @function Spring.GetMouseCursor - * @treturn string cursorName - * @treturn number cursorScale + * @return string cursorName + * @return number cursorScale */ int LuaUnsyncedRead::GetMouseCursor(lua_State* L) { @@ -3577,15 +3525,15 @@ int LuaUnsyncedRead::GetMouseCursor(lua_State* L) /*** * * @function Spring.GetMouseStartPosition - * @number button - * @treturn number x - * @treturn number y - * @treturn number camPosX - * @treturn number camPosY - * @treturn number camPosZ - * @treturn number dirX - * @treturn number dirY - * @treturn number dirZ + * @param button number + * @return number x + * @return number y + * @return number camPosX + * @return number camPosY + * @return number camPosZ + * @return number dirX + * @return number dirY + * @return number dirZ */ int LuaUnsyncedRead::GetMouseStartPosition(lua_State* L) { @@ -3618,7 +3566,7 @@ int LuaUnsyncedRead::GetMouseStartPosition(lua_State* L) /*** * * @function Spring.GetClipboard - * @treturn string text + * @return string text */ int LuaUnsyncedRead::GetClipboard(lua_State* L) { @@ -3634,7 +3582,7 @@ int LuaUnsyncedRead::GetClipboard(lua_State* L) /*** * * @function Spring.IsUserWriting - * @treturn bool + * @return boolean */ int LuaUnsyncedRead::IsUserWriting(lua_State* L) { @@ -3652,7 +3600,7 @@ int LuaUnsyncedRead::IsUserWriting(lua_State* L) /*** * * @function Spring.GetLastMessagePositions - * @treturn {xyz,...} message positions + * @return xyz[] message positions */ int LuaUnsyncedRead::GetLastMessagePositions(lua_State* L) { @@ -3673,10 +3621,9 @@ int LuaUnsyncedRead::GetLastMessagePositions(lua_State* L) /*** - * * @function Spring.GetConsoleBuffer - * @number maxLines - * @treturn nil|{{text=string,priority=number},...} pair array of (text, priority) + * @param maxLines number + * @return { text: string, priority: integer }[] buffer */ int LuaUnsyncedRead::GetConsoleBuffer(lua_State* L) { @@ -3710,9 +3657,8 @@ int LuaUnsyncedRead::GetConsoleBuffer(lua_State* L) /*** - * * @function Spring.GetCurrentTooltip - * @treturn string tooltip + * @return string tooltip */ int LuaUnsyncedRead::GetCurrentTooltip(lua_State* L) { @@ -3728,10 +3674,9 @@ int LuaUnsyncedRead::GetCurrentTooltip(lua_State* L) /*** - * * @function Spring.GetKeyFromScanSymbol - * @string scanSymbol - * @treturn string keyName + * @param scanSymbol string + * @return string keyName */ int LuaUnsyncedRead::GetKeyFromScanSymbol(lua_State* L) { @@ -3766,8 +3711,8 @@ int LuaUnsyncedRead::GetKeyFromScanSymbol(lua_State* L) /*** * * @function Spring.GetKeyState - * @number keyCode - * @treturn bool pressed + * @param keyCode number + * @return boolean pressed */ int LuaUnsyncedRead::GetKeyState(lua_State* L) { @@ -3780,10 +3725,10 @@ int LuaUnsyncedRead::GetKeyState(lua_State* L) /*** * * @function Spring.GetModKeyState - * @treturn bool alt - * @treturn bool ctrl - * @treturn bool meta - * @treturn bool shift + * @return boolean alt + * @return boolean ctrl + * @return boolean meta + * @return boolean shift */ int LuaUnsyncedRead::GetModKeyState(lua_State* L) { @@ -3798,7 +3743,7 @@ int LuaUnsyncedRead::GetModKeyState(lua_State* L) /*** * * @function Spring.GetPressedKeys - * @treturn {[number|string]=true,...} where keys are keyCodes or key names + * @return table where keys are keyCodes or key names */ int LuaUnsyncedRead::GetPressedKeys(lua_State* L) { @@ -3829,7 +3774,7 @@ int LuaUnsyncedRead::GetPressedKeys(lua_State* L) /*** * * @function Spring.GetPressedScans - * @treturn {[number|string]=true,...} where keys are scanCodes or scan names + * @return table where keys are scanCodes or scan names */ int LuaUnsyncedRead::GetPressedScans(lua_State* L) { @@ -3860,7 +3805,7 @@ int LuaUnsyncedRead::GetPressedScans(lua_State* L) /*** * * @function Spring.GetInvertQueueKey - * @treturn nil|number queueKey + * @return number? queueKey */ int LuaUnsyncedRead::GetInvertQueueKey(lua_State* L) { @@ -3875,8 +3820,8 @@ int LuaUnsyncedRead::GetInvertQueueKey(lua_State* L) /*** * * @function Spring.GetKeyCode - * @string keySym - * @treturn number keyCode + * @param keySym string + * @return number keyCode */ int LuaUnsyncedRead::GetKeyCode(lua_State* L) { @@ -3888,9 +3833,9 @@ int LuaUnsyncedRead::GetKeyCode(lua_State* L) /*** * * @function Spring.GetKeySymbol - * @number keyCode - * @treturn string keyCodeName - * @treturn string keyCodeDefaultName name when there are not aliases + * @param keyCode number + * @return string keyCodeName + * @return string keyCodeDefaultName name when there are not aliases */ int LuaUnsyncedRead::GetKeySymbol(lua_State* L) { @@ -3904,9 +3849,9 @@ int LuaUnsyncedRead::GetKeySymbol(lua_State* L) /*** * * @function Spring.GetScanSymbol - * @number scanCode - * @treturn string scanCodeName - * @treturn string scanCodeDefaultName name when there are not aliases + * @param scanCode number + * @return string scanCodeName + * @return string scanCodeDefaultName name when there are not aliases */ int LuaUnsyncedRead::GetScanSymbol(lua_State* L) { @@ -3917,24 +3862,23 @@ int LuaUnsyncedRead::GetScanSymbol(lua_State* L) } -/*** Keybinding spec - * - * @table keybindingSpec +/*** + * Keybinding * * Contains data about a keybinding * - * @string command - * @string extra - * @string boundWith + * @class KeyBinding + * @field command string + * @field extra string + * @field boundWith string */ /*** - * * @function Spring.GetKeyBindings - * @string[opt] keySet1 filters keybindings bound to this keyset - * @string[opt] keySet2 OR bound to this keyset - * @treturn {[keybindingSpec],...} + * @param keySet1 string? filters keybindings bound to this keyset + * @param keySet2 string? OR bound to this keyset + * @return KeyBinding[] */ int LuaUnsyncedRead::GetKeyBindings(lua_State* L) { @@ -3986,8 +3930,8 @@ int LuaUnsyncedRead::GetKeyBindings(lua_State* L) /*** * * @function Spring.GetActionHotKeys - * @string actionName - * @treturn nil|{[string],...} hotkeys + * @param actionName string + * @return string[]? hotkeys */ int LuaUnsyncedRead::GetActionHotKeys(lua_State* L) { @@ -4012,7 +3956,7 @@ int LuaUnsyncedRead::GetActionHotKeys(lua_State* L) /*** * * @function Spring.GetGroupList - * @treturn nil|{[number]=number,...} where keys are groupIDs and values are counts + * @return nil|table where keys are groupIDs and values are counts */ int LuaUnsyncedRead::GetGroupList(lua_State* L) { @@ -4040,7 +3984,7 @@ int LuaUnsyncedRead::GetGroupList(lua_State* L) /*** * * @function Spring.GetSelectedGroup - * @treturn number groupID -1 when no group selected + * @return number groupID -1 when no group selected */ int LuaUnsyncedRead::GetSelectedGroup(lua_State* L) { @@ -4052,8 +3996,8 @@ int LuaUnsyncedRead::GetSelectedGroup(lua_State* L) /*** * * @function Spring.GetUnitGroup - * @number unitID - * @treturn nil|number groupID + * @param unitID integer + * @return number? groupID */ int LuaUnsyncedRead::GetUnitGroup(lua_State* L) { @@ -4087,8 +4031,8 @@ static inline const CGroup* GetGroupFromArg(lua_State* L, int arg) /*** * * @function Spring.GetGroupUnits - * @number groupID - * @treturn nil|{[number],...} unitIDs + * @param groupID integer + * @return nil|number[] unitIDs */ int LuaUnsyncedRead::GetGroupUnits(lua_State* L) { @@ -4104,8 +4048,8 @@ int LuaUnsyncedRead::GetGroupUnits(lua_State* L) /*** * * @function Spring.GetGroupUnitsSorted - * @number groupID - * @treturn nil|{[number]={[number],...},...} where keys are unitDefIDs and values are unitIDs + * @param groupID integer + * @return nil|table where keys are unitDefIDs and values are unitIDs */ int LuaUnsyncedRead::GetGroupUnitsSorted(lua_State* L) { @@ -4121,8 +4065,8 @@ int LuaUnsyncedRead::GetGroupUnitsSorted(lua_State* L) /*** * * @function Spring.GetGroupUnitsCounts - * @number groupID - * @treturn nil|{[number]=number,...} where keys are unitDefIDs and values are counts + * @param groupID integer + * @return nil|table where keys are unitDefIDs and values are counts */ int LuaUnsyncedRead::GetGroupUnitsCounts(lua_State* L) { @@ -4138,8 +4082,8 @@ int LuaUnsyncedRead::GetGroupUnitsCounts(lua_State* L) /*** * * @function Spring.GetGroupUnitsCount - * @number groupID - * @treturn nil|number groupSize + * @param groupID integer + * @return number? groupSize */ int LuaUnsyncedRead::GetGroupUnitsCount(lua_State* L) { @@ -4158,28 +4102,27 @@ int LuaUnsyncedRead::GetGroupUnitsCount(lua_State* L) ******************************************************************************/ -/*** Roster spec - * - * @table rosterSpec +/*** Roster * * Contains data about a player * - * @string name - * @number playerID - * @number teamID - * @number allyTeamID - * @bool spectator - * @number cpuUsage in order to find the progress, use: cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000 for the progress - * @number pingTime if -1, the player is pathfinding + * @class Roster + * @field name string + * @field playerID integer + * @field teamID integer + * @field allyTeamID integer + * @field spectator boolean + * @field cpuUsage number in order to find the progress, use: cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000 for the progress + * @field pingTime number if -1, the player is pathfinding */ /*** * * @function Spring.GetPlayerRoster - * @number[opt] sortType return unsorted if unspecified. Disabled = 0, Allies = 1, TeamID = 2, PlayerName = 3, PlayerCPU = 4, PlayerPing = 5 - * @bool[opt=false] showPathingPlayers - * @treturn nil|{[rosterSpec],...} playerTable + * @param sortType number? return unsorted if unspecified. Disabled = 0, Allies = 1, TeamID = 2, PlayerName = 3, PlayerCPU = 4, PlayerPing = 5 + * @param showPathingPlayers boolean? (Default: false) + * @return Roster[]? playerTable */ int LuaUnsyncedRead::GetPlayerRoster(lua_State* L) { @@ -4213,9 +4156,9 @@ int LuaUnsyncedRead::GetPlayerRoster(lua_State* L) /*** * * @function Spring.GetPlayerTraffic - * @number playerID - * @number packetID[opt] - * @treturn number traffic + * @param playerID integer + * @param packetID integer? + * @return number traffic */ int LuaUnsyncedRead::GetPlayerTraffic(lua_State* L) { @@ -4265,12 +4208,12 @@ int LuaUnsyncedRead::GetPlayerTraffic(lua_State* L) /*** * * @function Spring.GetPlayerStatistics - * @number playerID - * @treturn nil|number mousePixels nil when invalid playerID - * @treturn number mouseClicks - * @treturn number keyPresses - * @treturn number numCommands - * @treturn number unitCommands + * @param playerID integer + * @return number? mousePixels nil when invalid playerID + * @return number mouseClicks + * @return number keyPresses + * @return number numCommands + * @return number unitCommands */ int LuaUnsyncedRead::GetPlayerStatistics(lua_State* L) { @@ -4300,29 +4243,28 @@ int LuaUnsyncedRead::GetPlayerStatistics(lua_State* L) ******************************************************************************/ -/*** Configuration spec - * - * @table configSpec +/*** Configuration * * Contains data about a configuration, only name and type are guaranteed * - * @string name - * @string type - * @string description - * @string defaultValue - * @string minimumValue - * @string maximumValue - * @string safemodeValue - * @string declarationFile - * @string declarationLine - * @bool readOnly + * @class Configuration + * @field name string + * @field type string + * @field description string + * @field defaultValue string + * @field minimumValue string + * @field maximumValue string + * @field safemodeValue string + * @field declarationFile string + * @field declarationLine string + * @field readOnly boolean */ /*** * * @function Spring.GetConfigParams - * @treturn {[configSpec],...} + * @return Configuration[] */ int LuaUnsyncedRead::GetConfigParams(lua_State* L) { @@ -4396,9 +4338,9 @@ int LuaUnsyncedRead::GetConfigParams(lua_State* L) /*** * * @function Spring.GetConfigInt - * @string name - * @tparam[opt=0] number|nil default - * @treturn nil|number configInt + * @param name string + * @param default number? (Default: `0`) + * @return number? configInt */ int LuaUnsyncedRead::GetConfigInt(lua_State* L) { @@ -4417,9 +4359,9 @@ int LuaUnsyncedRead::GetConfigInt(lua_State* L) /*** * * @function Spring.GetConfigFloat - * @string name - * @tparam[opt=0] number|nil default - * @treturn nil|number configFloat + * @param name string + * @param default number? (Default: `0`) + * @return number? configFloat */ int LuaUnsyncedRead::GetConfigFloat(lua_State* L) { @@ -4438,9 +4380,9 @@ int LuaUnsyncedRead::GetConfigFloat(lua_State* L) /*** * * @function Spring.GetConfigString - * @string name - * @tparam[opt=""] string|nil default - * @treturn nil|number configString + * @param name string + * @param default string? (Default: `""`) + * @return number? configString */ int LuaUnsyncedRead::GetConfigString(lua_State* L) { @@ -4459,7 +4401,7 @@ int LuaUnsyncedRead::GetConfigString(lua_State* L) /*** * * @function Spring.GetLogSections - * @treturn {[string]=number,...} sections where keys are names and loglevel are values. E.g. `{ "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }` + * @return table sections where keys are names and loglevel are values. E.g. `{ "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }` */ int LuaUnsyncedRead::GetLogSections(lua_State* L) { const int numLogSections = log_filter_section_getNumRegisteredSections(); @@ -4488,7 +4430,7 @@ int LuaUnsyncedRead::GetLogSections(lua_State* L) { * * @function Spring.GetAllGroundDecals * - * @treturn {[number],...} decalIDs + * @return number[] decalIDs */ int LuaUnsyncedRead::GetAllGroundDecals(lua_State* L) { @@ -4521,9 +4463,9 @@ int LuaUnsyncedRead::GetAllGroundDecals(lua_State* L) /*** * * @function Spring.GetGroundDecalMiddlePos - * @number decalID - * @treturn nil|number posX - * @treturn number posZ + * @param decalID integer + * @return number? posX + * @return number posZ */ int LuaUnsyncedRead::GetGroundDecalMiddlePos(lua_State* L) { @@ -4542,15 +4484,15 @@ int LuaUnsyncedRead::GetGroundDecalMiddlePos(lua_State* L) /*** * * @function Spring.GetDecalQuadPos - * @number decalID - * @treturn nil|number posTL.x - * @treturn number posTL.z - * @treturn number posTR.x - * @treturn number posTR.z - * @treturn number posBR.x - * @treturn number posBR.z - * @treturn number posBL.x - * @treturn number posBL.z + * @param decalID integer + * @return number? posTL.x + * @return number posTL.z + * @return number posTR.x + * @return number posTR.z + * @return number posBR.x + * @return number posBR.z + * @return number posBL.x + * @return number posBL.z */ int LuaUnsyncedRead::GetGroundDecalQuadPos(lua_State* L) { @@ -4575,10 +4517,10 @@ int LuaUnsyncedRead::GetGroundDecalQuadPos(lua_State* L) /*** * * @function Spring.GetGroundDecalSizeAndHeight - * @number decalID - * @treturn nil|number sizeX - * @treturn number sizeY - * @treturn number projCubeHeight + * @param decalID integer + * @return number? sizeX + * @return number sizeY + * @return number projCubeHeight */ int LuaUnsyncedRead::GetGroundDecalSizeAndHeight(lua_State* L) { @@ -4599,8 +4541,8 @@ int LuaUnsyncedRead::GetGroundDecalSizeAndHeight(lua_State* L) /*** * * @function Spring.GetGroundDecalRotation - * @number decalID - * @treturn nil|number rotation in radians + * @param decalID integer + * @return number? rotation in radians */ int LuaUnsyncedRead::GetGroundDecalRotation(lua_State* L) { @@ -4618,9 +4560,9 @@ int LuaUnsyncedRead::GetGroundDecalRotation(lua_State* L) /*** * * @function Spring.GetGroundDecalTexture - * @number decalID - * @bool[opt=true] isMainTex If false, it gets the normals/glow map - * @treturn nil|string texture + * @param decalID integer + * @param isMainTex boolean? (Default: true) If false, it gets the normals/glow map + * @return nil|string texture */ int LuaUnsyncedRead::GetGroundDecalTexture(lua_State* L) { @@ -4633,8 +4575,8 @@ int LuaUnsyncedRead::GetGroundDecalTexture(lua_State* L) /*** * * @function Spring.GetDecalTextures - * @bool[opt=true] isMainTex If false, it gets the texture for normals/glow maps - * @treturn {[string],...} textureNames All textures on the atlas and available for use in SetGroundDecalTexture + * @param isMainTex boolean? (Default: true) If false, it gets the texture for normals/glow maps + * @return string[] textureNames All textures on the atlas and available for use in SetGroundDecalTexture */ int LuaUnsyncedRead::GetGroundDecalTextures(lua_State* L) { @@ -4648,9 +4590,9 @@ int LuaUnsyncedRead::GetGroundDecalTextures(lua_State* L) /*** * * @function Spring.SetGroundDecalTextureParams - * @number decalID - * @treturn nil|number texWrapDistance if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos - * @treturn number texTraveledDistance shifts the texture repetition defined by texWrapFactor so the texture of a next line in the continuous multiline can start where the previous finished. For that it should collect all elmo lengths of the previously set multiline segments. + * @param decalID integer + * @return number? texWrapDistance if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos + * @return number texTraveledDistance shifts the texture repetition defined by texWrapFactor so the texture of a next line in the continuous multiline can start where the previous finished. For that it should collect all elmo lengths of the previously set multiline segments. */ int LuaUnsyncedRead::GetGroundDecalTextureParams(lua_State* L) { @@ -4669,9 +4611,9 @@ int LuaUnsyncedRead::GetGroundDecalTextureParams(lua_State* L) /*** * * @function Spring.GetGroundDecalAlpha - * @number decalID - * @treturn nil|number alpha Between 0 and 1 - * @treturn number alphaFalloff Between 0 and 1, per second + * @param decalID integer + * @return number? alpha Between 0 and 1 + * @return number alphaFalloff Between 0 and 1, per second */ int LuaUnsyncedRead::GetGroundDecalAlpha(lua_State* L) { @@ -4692,10 +4634,10 @@ int LuaUnsyncedRead::GetGroundDecalAlpha(lua_State* L) * * If all three equal 0, the decal follows the normals of ground at midpoint * - * @number decalID - * @treturn nil|number normal.x - * @treturn number normal.y - * @treturn number normal.z + * @param decalID integer + * @return number? normal.x + * @return number normal.y + * @return number normal.z */ int LuaUnsyncedRead::GetGroundDecalNormal(lua_State* L) { @@ -4716,11 +4658,11 @@ int LuaUnsyncedRead::GetGroundDecalNormal(lua_State* L) * @function Spring.GetGroundDecalTint * Gets the tint of the ground decal. * A color of (0.5, 0.5, 0.5, 0.5) is effectively no tint - * @number decalID - * @treturn nil|number tintR - * @treturn number tintG - * @treturn number tintB - * @treturn number tintA + * @param decalID integer + * @return number? tintR + * @return number tintG + * @return number tintB + * @return number tintA */ int LuaUnsyncedRead::GetGroundDecalTint(lua_State* L) { @@ -4742,12 +4684,12 @@ int LuaUnsyncedRead::GetGroundDecalTint(lua_State* L) * * @function Spring.GetGroundDecalMisc * Returns less important parameters of a ground decal - * @number decalID - * @treturn nil|number dotElimExp - * @treturn number refHeight - * @treturn number minHeight - * @treturn number maxHeight - * @treturn number forceHeightMode + * @param decalID integer + * @return number? dotElimExp + * @return number refHeight + * @return number minHeight + * @return number maxHeight + * @return number forceHeightMode */ int LuaUnsyncedRead::GetGroundDecalMisc(lua_State* L) { @@ -4770,9 +4712,9 @@ int LuaUnsyncedRead::GetGroundDecalMisc(lua_State* L) * * Min can be not equal to max for "gradient" style decals, e.g. unit tracks * - * @number decalID - * @treturn nil|number creationFrameMin - * @treturn number creationFrameMax + * @param decalID integer + * @return number? creationFrameMin + * @return number creationFrameMax */ int LuaUnsyncedRead::GetGroundDecalCreationFrame(lua_State* L) { @@ -4791,8 +4733,8 @@ int LuaUnsyncedRead::GetGroundDecalCreationFrame(lua_State* L) /*** * * @function Spring.GetGroundDecalOwner - * @number decalID - * @treturn nil|number unitID|number featureID(+MAX_UNITS) + * @param decalID integer + * @return number? unitID|number featureID(+MAX_UNITS) */ int LuaUnsyncedRead::GetGroundDecalOwner(lua_State* L) { @@ -4812,8 +4754,8 @@ int LuaUnsyncedRead::GetGroundDecalOwner(lua_State* L) /*** * * @function Spring.GetGroundDecalType - * @number decalID - * @treturn nil|string type "explosion"|"plate"|"lua"|"track"|"unknown" + * @param decalID integer + * @return nil|string type "explosion"|"plate"|"lua"|"track"|"unknown" */ int LuaUnsyncedRead::GetGroundDecalType(lua_State* L) { @@ -4854,8 +4796,8 @@ int LuaUnsyncedRead::GetGroundDecalType(lua_State* L) /*** * * @function Spring.GetSyncedGCInfo - * @bool[opt=false] collectGC collect before returning metric - * @treturn nil|number GC values are expressed in Kbytes: #bytes/2^10 + * @param collectGC boolean? (Default: false) collect before returning metric + * @return number? GC values are expressed in Kbytes: #bytes/2^10 */ int LuaUnsyncedRead::GetSyncedGCInfo(lua_State* L) { if (luaRules == nullptr) @@ -4881,8 +4823,8 @@ int LuaUnsyncedRead::GetSyncedGCInfo(lua_State* L) { /*** * * @function Spring.SolveNURBSCurve - * @number groupID - * @treturn nil|{[number],...} unitIDs + * @param groupID integer + * @return number[]? unitIDs */ int LuaUnsyncedRead::SolveNURBSCurve(lua_State* L) { diff --git a/rts/Lua/LuaUtils.cpp b/rts/Lua/LuaUtils.cpp index b109d1ed54..26c6a0fd54 100644 --- a/rts/Lua/LuaUtils.cpp +++ b/rts/Lua/LuaUtils.cpp @@ -1156,6 +1156,21 @@ void LuaUtils::ParseCommandArray( } } +/** + * @alias Facing + * | 0 # South + * | 1 # East + * | 2 # North + * | 3 # West + * | "s" # South + * | "e" # East + * | "n" # North + * | "w" # West + * | "south" # South + * | "east" # East + * | "north" # North + * | "west" # West + */ int LuaUtils::ParseFacing(lua_State* L, const char* caller, int index) { diff --git a/rts/Lua/LuaVAO.cpp b/rts/Lua/LuaVAO.cpp index 90d0212690..ca33bffb04 100644 --- a/rts/Lua/LuaVAO.cpp +++ b/rts/Lua/LuaVAO.cpp @@ -7,7 +7,6 @@ /****************************************************************************** - * @module LuaVAO * * @see rts/Lua/LuaVAO.cpp ******************************************************************************/ @@ -73,14 +72,15 @@ LuaVAOs::~LuaVAOs() luaVAOs.clear(); } - /*** - * - * @function gl.GetVAO - * @treturn nil|VAO the VAO ref on success, else nil - * @usage + * Example: + * ``` * local myVAO = gl.GetVAO() * if myVAO == nil then Spring.Echo("Failed to get VAO") end + * ``` + * + * @function gl.GetVAO + * @return VAO? vao The VAO ref on success, else `nil` */ int LuaVAOs::GetVAO(lua_State* L) { diff --git a/rts/Lua/LuaVAOImpl.cpp b/rts/Lua/LuaVAOImpl.cpp index 7194740bc4..03567ba54e 100644 --- a/rts/Lua/LuaVAOImpl.cpp +++ b/rts/Lua/LuaVAOImpl.cpp @@ -15,14 +15,14 @@ #include "LuaUtils.h" - -/****************************************************************************** +/*** * Vertex Array Object - * @classmod VAO - * + * + * @class VAO + * @table VAO * @see LuaVAO.GetVAO * @see rts/Lua/LuaVAOImpl.cpp -******************************************************************************/ + */ LuaVAOImpl::LuaVAOImpl() @@ -39,7 +39,7 @@ LuaVAOImpl::LuaVAOImpl() /*** * * @function VAO:Delete - * @treturn nil + * @return nil */ void LuaVAOImpl::Delete() { @@ -93,8 +93,8 @@ void LuaVAOImpl::AttachBufferImpl(const std::shared_ptr& luaVBO, std /*** Attachs a VBO to be used as a vertex buffer * * @function VAO:AttachVertexBuffer - * @tparam VBO vbo - * @treturn nil + * @param vbo VBO + * @return nil */ void LuaVAOImpl::AttachVertexBuffer(const LuaVBOImplSP& luaVBO) { @@ -105,8 +105,8 @@ void LuaVAOImpl::AttachVertexBuffer(const LuaVBOImplSP& luaVBO) /*** Attachs a VBO to be used as an instance buffer * * @function VAO:AttachInstanceBuffer - * @tparam VBO vbo - * @treturn nil + * @param vbo VBO + * @return nil */ void LuaVAOImpl::AttachInstanceBuffer(const LuaVBOImplSP& luaVBO) { @@ -117,8 +117,8 @@ void LuaVAOImpl::AttachInstanceBuffer(const LuaVBOImplSP& luaVBO) /*** Attachs a VBO to be used as an index buffer * * @function VAO:AttachIndexBuffer - * @tparam VBO vbo - * @treturn nil + * @param vbo VBO + * @return nil */ void LuaVAOImpl::AttachIndexBuffer(const LuaVBOImplSP& luaVBO) { @@ -367,12 +367,12 @@ LuaVAOImpl::DrawCheckResult LuaVAOImpl::DrawCheck(GLenum mode, const DrawCheckIn /*** * * @function VAO:DrawArrays - * @number glEnum primitivesMode - * @number[opt] vertexCount - * @number[opt] vertexFirst - * @number[opt] instanceCount - * @number[opt] instanceFirst - * @treturn nil + * @param glEnum number primitivesMode + * @param vertexCount number? + * @param vertexFirst number? + * @param instanceCount number? + * @param instanceFirst number? + * @return nil */ void LuaVAOImpl::DrawArrays(GLenum mode, sol::optional vertCountOpt, sol::optional vertexFirstOpt, sol::optional instanceCountOpt, sol::optional instanceFirstOpt) { @@ -404,13 +404,13 @@ void LuaVAOImpl::DrawArrays(GLenum mode, sol::optional vertCountOpt, sol::o /*** * * @function VAO:DrawElements - * @number glEnum primitivesMode - * @number[opt] drawCount - * @number[opt] baseIndex - * @number[opt] instanceCount - * @number[opt] baseVertex - * @number[opt] baseInstance - * @treturn nil + * @param glEnum number primitivesMode + * @param drawCount number? + * @param baseIndex number? + * @param instanceCount number? + * @param baseVertex number? + * @param baseInstance number? + * @return nil */ void LuaVAOImpl::DrawElements(GLenum mode, sol::optional indCountOpt, sol::optional indElemOffsetOpt, sol::optional instanceCountOpt, sol::optional baseVertexOpt, sol::optional instanceFirstOpt) { @@ -466,8 +466,8 @@ void LuaVAOImpl::ClearSubmission() /*** * * @function VAO:AddUnitsToSubmission - * @tparam number|{number,...} unitIDs - * @treturn number submittedCount + * @param unitIDs number|number[] + * @return number submittedCount */ int LuaVAOImpl::AddUnitsToSubmission(int id) { return AddObjectsToSubmissionImpl(id); } int LuaVAOImpl::AddUnitsToSubmission(const sol::stack_table& ids) { return AddObjectsToSubmissionImpl(ids); } @@ -476,8 +476,8 @@ int LuaVAOImpl::AddUnitsToSubmission(const sol::stack_table& ids) { return AddO /*** * * @function VAO:AddFeaturesToSubmission - * @tparam number|{number,...} featureIDs - * @treturn number submittedCount + * @param featureIDs number|number[] + * @return number submittedCount */ int LuaVAOImpl::AddFeaturesToSubmission(int id) { return AddObjectsToSubmissionImpl(id); } int LuaVAOImpl::AddFeaturesToSubmission(const sol::stack_table& ids) { return AddObjectsToSubmissionImpl(ids); } @@ -486,8 +486,8 @@ int LuaVAOImpl::AddFeaturesToSubmission(const sol::stack_table& ids) { return Ad /*** * * @function VAO:AddUnitDefsToSubmission - * @tparam number|{number,...} unitDefIDs - * @treturn number submittedCount + * @param unitDefIDs number|number[] + * @return number submittedCount */ int LuaVAOImpl::AddUnitDefsToSubmission(int id) { return AddObjectsToSubmissionImpl(id); } int LuaVAOImpl::AddUnitDefsToSubmission(const sol::stack_table& ids) { return AddObjectsToSubmissionImpl(ids); } @@ -496,8 +496,8 @@ int LuaVAOImpl::AddUnitDefsToSubmission(const sol::stack_table& ids) { return Ad /*** * * @function VAO:AddFeatureDefsToSubmission - * @tparam number|{number,...} featureDefIDs - * @treturn number submittedCount + * @param featureDefIDs number|number[] + * @return number submittedCount */ int LuaVAOImpl::AddFeatureDefsToSubmission(int id) { return AddObjectsToSubmissionImpl(id); } int LuaVAOImpl::AddFeatureDefsToSubmission(const sol::stack_table& ids) { return AddObjectsToSubmissionImpl(ids); } @@ -506,8 +506,8 @@ int LuaVAOImpl::AddFeatureDefsToSubmission(const sol::stack_table& ids) { return /*** * * @function VAO:RemoveFromSubmission - * @tparam number index - * @treturn nil + * @param index number + * @return nil */ void LuaVAOImpl::RemoveFromSubmission(int idx) { @@ -529,7 +529,7 @@ void LuaVAOImpl::RemoveFromSubmission(int idx) /*** * * @function VAO:Submit - * @treturn nil + * @return nil */ void LuaVAOImpl::Submit() { diff --git a/rts/Lua/LuaVBO.cpp b/rts/Lua/LuaVBO.cpp index 5e21066f35..9a725c5d87 100644 --- a/rts/Lua/LuaVBO.cpp +++ b/rts/Lua/LuaVBO.cpp @@ -12,7 +12,6 @@ /****************************************************************************** - * @module LuaVBO * * @see rts/Lua/LuaVBO.cpp ******************************************************************************/ @@ -120,22 +119,39 @@ LuaVBOs::~LuaVBOs() luaVBOs.clear(); } +/*** + * @alias GLBufferType + * | GL.ARRAY_BUFFER + * | GL.ELEMENT_ARRAY_BUFFER + * | GL.UNIFORM_BUFFER + * | GL.SHADER_STORAGE_BUFFER + */ + /*** + * Example: + * + * ```lua + * local myVBO = gl.GetVBO() + * if myVBO == nil then Spring.Echo("Failed to get VBO") end + * ``` * * @function gl.GetVBO - * @number[opt=GL.ARRAY_BUFFER] bufferType one of [`GL.ARRAY_BUFFER`, - * `GL.ELEMENT_ARRAY_BUFFER`, `GL.UNIFORM_BUFFER`, `GL.SHADER_STORAGE_BUFFER`]. + * + * @param bufferType GLBufferType? (Default: GL.ARRAY_BUFFER) * - * Defaults to `GL.ARRAY_BUFFER`, which you should use for vertex data, and - * `GL.ELEMENT_ARRAY_BUFFER` should be used for vertex indices. - * @bool[opt=true] freqUpdated whether should be updated frequently, when false - * will be updated only once - * @treturn nil|VBO the VBO ref on success, nil if not supported/or other error + * Use `GL.ARRAY_BUFFER` for vertex data and + * `GL.ELEMENT_ARRAY_BUFFER` for vertex indices. + * + * @param freqUpdated boolean? (Default: true) + * + * `true` to updated frequently, `false` to update only once. + * + * @return VBO? VBO + * + * The VBO ref on success, or nil if not supported or an error occurred. + * * @see GL.OpenGL_Buffer_Types - * @usage - * local myVBO = gl.GetVBO() - * if myVBO == nil then Spring.Echo("Failed to get VBO") end */ int LuaVBOs::GetVBO(lua_State* L) { diff --git a/rts/Lua/LuaVBOImpl.cpp b/rts/Lua/LuaVBOImpl.cpp index 62a85bf99f..0d4793ac14 100644 --- a/rts/Lua/LuaVBOImpl.cpp +++ b/rts/Lua/LuaVBOImpl.cpp @@ -34,7 +34,7 @@ /****************************************************************************** * Vertex Buffer Object - * @classmod VBO + * @class VBO * * @see LuaVBO.GetVBO * @see rts/Lua/LuaVBOImpl.cpp @@ -109,7 +109,7 @@ inline void LuaVBOImpl::InstanceBufferCheckAndFormatCheck(int attrID, const char /*** * * @function VBO:Delete - * @treturn nil + * @return nil */ void LuaVBOImpl::Delete() { @@ -456,11 +456,54 @@ bool LuaVBOImpl::DefineElementArray(const sol::optional attribDefAr return true; } +/** + * @alias VBODataType + * | GL.BYTE + * | GL.UNSIGNED_BYTE + * | GL.SHORT + * | GL.UNSIGNED_SHORT + * | GL.INT + * | GL.UNSIGNED_INT + * | GL.FLOAT + */ -/*** Allows you to specify what kind of VBO you will be using. - * - * @function VBO:Define +/** + * @class VBOAttributeDef + * + * @field id integer + * The location in the vertex shader layout e.g.: layout (location = 0) in vec2 + * aPos. optional attrib, specifies location in the vertex shader. If not + * specified the implementation will increment the counter starting from 0. + * There can be maximum 16 attributes (so id of 15 is max). + * + * @field name string + * + * The name for this VBO, only used for debugging. + * + * @field size integer? + * + * Defaults to to 4 for VBO. The number of floats that constitute 1 element in + * this buffer. e.g. for the previous layout (location = 0) in vec2 aPos, it + * would be size = 2. + * + * @field type VBODataType (Default: `GL.FLOAT`) + * + * The datatype of this element. + * + * @field normalized boolean? (Defaults: `false`) + * + * It's possible to submit say normal without normalizing them first, normalized + * will make sure data is normalized. + */ + + +/*** + * Specify the kind of VBO you will be using. * + * ```lua + * @usage terrainVertexVBO:Define(numPoints, {{ id = 0, name = "pos", size = 2 }}) + * ``` + * * It is usually an array of vertex/color/uv data, but can also be an array of * instance uniforms. * @@ -470,40 +513,26 @@ bool LuaVBOImpl::DefineElementArray(const sol::optional attribDefAr * * If you want say 5 elements, and each element is defined in the layout: * - * {id = 0, name = "first", size = 1},{id = 1, name = "second", size = 2}} + * ```lua + * {id = 0, name = "first", size = 1},{id = 1, name = "second", size = 2}} + * ``` * - * , then the total size of your VBO will be 5 * (1 + 2). + * Then the total size of your VBO will be `5 * (1 + 2)`. * - * They will be laid out consecutively: [1,2],[1,2],[1,2],[1,2],[1,2]. + * They will be laid out consecutively: `[1,2],[1,2],[1,2],[1,2],[1,2]`. * - * This is important for when you call VBO:Upload, you need to make sure you + * This is important for when you call `VBO:Upload`, you need to make sure you * enter your data into the Lua array correctly. * - * @number size the maximum number of elements this VBO can have. - * @tparam number|{{number,number,number,number,number},...} attribs + * @function VBO:Define + * @param size number The maximum number of elements this VBO can have. + * @param attribs number|VBOAttributeDef[] * * When number, the maximum number of elements this VBO can have. * - * Otherwise, an array of arrays specifying the layout composed of: - * - * - `id`: the location in the vertex shader layout e.g.: layout (location = 0) - * in vec2 aPos. optional attrib, specifies location in the vertex shader. - * If not specified the implementation will increment the counter starting from 0. - * There can be maximum 16 attributes (so id of 15 is max). - * - `name`: the name for this VBO, only used for debugging - * - `size`: optional, defaults to 4 for VBO. The number of floats that - * constitute 1 element in this buffer. O.g. for the previous layout - * (location = 0) in vec2 aPos, it would be size = 2. - * - `type`: is the datatype of this element, can be: `GL.BYTE`, - * `GL.UNSIGNED_BYTE`, `GL.SHORT`, `GL.UNSIGNED_SHORT`, `GL.INT`, - * `GL.UNSIGNED_INT`, `GL.FLOAT`. Default is `GL.FLOAT`. - * - `normalized`: it's possible to submit say normal without normalizing them - * first, normalized will make sure data is normalized. - * Optional attrib, defaults to false. - * - * @treturn nil + * Otherwise, an array of arrays specifying the layout. * - * @usage terrainVertexVBO:Define(numPoints, { {id = 0, name = "pos", size = 2}, }) + * @return nil * @see GL.OpenGL_Data_Types * @see VBO:Upload */ @@ -557,9 +586,9 @@ void LuaVBOImpl::Define(const int elementsCount, const sol::optional LuaVBOImpl::GetBufferSize() { @@ -571,28 +600,37 @@ std::tuple LuaVBOImpl::GetBufferSize() } -/*** Uploads the data (array of floats) into the VBO +/*** + * Uploads the data (array of floats) into the VBO * - * @function VBO:Upload - * @tparam {number,...} vboData a lua array of values to upload into the - * VBO - * @number[opt=-1] attributeIndex If supplied with non-default value then the - * data from vboData will only be used to upload the data to this particular - * attribute. - * The whole vboData is expected to contain only attributeIndex data. - * Otherwise all attributes get updated sequentially across attributes and elements. - * @number[opt=0] elemOffset which VBO element to start uploading data from Lua array into - * @number[opt=0] luaStartIndex start uploading from that element in supplied Lua array - * @number[opt] luaFinishIndex consider this element the last element in Lua array - * @treturn {number, ...} indexData - * @treturn number elemOffset - * @treturn number|{number,number,number,number} attrID - * @usage + * ```lua * vbo:Upload(posArray, 0, 1) * -- 0 is offset into vbo (on GPU) in this case no offset * -- 1 is lua index index into the Lua table, in this case it's same as default * -- Upload will upload from luaOffset to end of lua array + * ``` + * + * ```lua * @usage rectInstanceVBO:Upload({1},0) + * ``` + * + * @function VBO:Upload + * @param vboData number[] a lua array of values to upload into the VBO + * @param attributeIndex integer? (Default: -1) + * + * If supplied with non-default value then the data from vboData will only be + * used to upload the data to this particular attribute. + * + * The whole vboData is expected to contain only attributeIndex data. + * + * Otherwise all attributes get updated sequentially across attributes and elements. + * + * @param elemOffset integer? (Default: 0) Which VBO element to start uploading data from Lua array into. + * @param luaStartIndex integer? (Default: 1) Start uploading from that element in supplied Lua array. + * @param luaFinishIndex integer? Consider this element the last element in Lua array. + * @return number[] indexData + * @return integer elemOffset + * @return integer|[integer,integer,integer,integer] attrID * @see VBO:Define */ size_t LuaVBOImpl::Upload(const sol::stack_table& luaTblData, sol::optional attribIdxOpt, sol::optional elemOffsetOpt, sol::optional luaStartIndexOpt, sol::optional luaFinishIndexOpt) @@ -640,14 +678,14 @@ size_t LuaVBOImpl::Upload(const sol::stack_table& luaTblData, sol::optional /*** * * @function VBO:Download - * @number[opt=-1] attributeIndex when supplied with non-default value: only data + * @param attributeIndex integer? (Default: -1) when supplied with non-default value: only data * from specified attribute will be downloaded - otherwise all attributes are * downloaded - * @number[opt=0] elementOffset download data starting from this element - * @number[opt] elementCount number of elements to download - * @bool[opt=false] forceGPURead force downloading the data from GPU buffer as opposed + * @param elementOffset integer? (Default: 0) download data starting from this element + * @param elementCount number? number of elements to download + * @param forceGPURead boolean? (Default: false) force downloading the data from GPU buffer as opposed * to using shadow RAM buffer - * @treturn {{number,...},...} vboData + * @return [number, ...][] vboData */ sol::as_table_t> LuaVBOImpl::Download(sol::optional attribIdxOpt, sol::optional elemOffsetOpt, sol::optional elemCountOpt, sol::optional forceGPUReadOpt) { @@ -1152,7 +1190,7 @@ size_t LuaVBOImpl::UploadImpl(const std::vector& dataVec, uint32_t elemOffs * * Also fills in VBO definition data as they're set for engine models (no need to do VBO:Define()). * - * @treturn nil|number buffer size in bytes + * @return nil|number buffer size in bytes */ size_t LuaVBOImpl::ModelsVBO() { @@ -1173,22 +1211,23 @@ size_t LuaVBOImpl::ModelsVBO() * matrix in global matrices SSBO and offset to uniform buffer structure in * global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as * well as some auxiliary data ushc as draw flags and team index. - * - * @tparam number|{number,...} unitDefIDs - * @number attrID - * @number[opt] teamIdOpt - * @number[opt] elementOffset - * @treturn {number,number,number,number} instanceData - * @treturn number elementOffset - * @treturn attrID - * @usage - * Data Layout - * + * + * Data Layout: + * ``` * SInstanceData: * , matOffset{ matOffset_ } // updated during the following draw frames * , uniOffset{ uniOffset_ } // updated during the following draw frames * , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames * , aux1 { 0u } + * ``` + * + * @param unitDefIDs number|number[] + * @param attrID integer + * @param teamIdOpt integer? + * @param elementOffset integer? + * @return [number,number,number,number] instanceData + * @return integer elementOffset + * @return integer attrID */ size_t LuaVBOImpl::InstanceDataFromUnitDefIDs(int id, int attrID, sol::optional teamIdOpt, sol::optional elemOffsetOpt) { @@ -1211,22 +1250,23 @@ size_t LuaVBOImpl::InstanceDataFromUnitDefIDs(const sol::stack_table& ids, int a * matrix in global matrices SSBO and offset to uniform buffer structure in * global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as * well as some auxiliary data ushc as draw flags and team index. - * - * @tparam number|{number,...} featureDefIDs - * @number attrID - * @number[opt] teamIdOpt - * @number[opt] elementOffset - * @treturn {number,number,number,number} instanceData - * @treturn number elementOffset - * @treturn attrID - * @usage + * * Data Layout - * + * ``` * SInstanceData: * , matOffset{ matOffset_ } // updated during the following draw frames * , uniOffset{ uniOffset_ } // updated during the following draw frames * , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames * , aux1 { 0u } + * ``` + * + * @param featureDefIDs number|number[] + * @param attrID integer + * @param teamIdOpt integer? + * @param elementOffset integer? + * @return [number,number,number,number] instanceData + * @return integer elementOffset + * @return integer attrID */ size_t LuaVBOImpl::InstanceDataFromFeatureDefIDs(int id, int attrID, sol::optional teamIdOpt, sol::optional elemOffsetOpt) { @@ -1249,22 +1289,24 @@ size_t LuaVBOImpl::InstanceDataFromFeatureDefIDs(const sol::stack_table& ids, in * matrix in global matrices SSBO and offset to uniform buffer structure in * global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as * well as some auxiliary data ushc as draw flags and team index. - * - * @tparam number|{number,...} unitIDs - * @number attrID - * @number[opt] teamIdOpt - * @number[opt] elementOffset - * @treturn {number,number,number,number} instanceData - * @treturn number elementOffset - * @treturn attrID - * @usage + * * Data Layout * + * ``` * SInstanceData: * , matOffset{ matOffset_ } // updated during the following draw frames * , uniOffset{ uniOffset_ } // updated during the following draw frames * , info{ teamIndex, drawFlags, 0, 0 } // not updated during the following draw frames * , aux1 { 0u } + * ``` + * + * @param unitIDs number|number[] + * @param attrID integer + * @param teamIdOpt integer? + * @param elementOffset integer? + * @return [number,number,number,number] instanceData + * @return integer elementOffset + * @return integer attrID */ size_t LuaVBOImpl::InstanceDataFromUnitIDs(int id, int attrID, sol::optional elemOffsetOpt) { @@ -1286,13 +1328,13 @@ size_t LuaVBOImpl::InstanceDataFromUnitIDs(const sol::stack_table& ids, int attr * global per unit/feature uniform SSBO (unused for Unit/FeatureDefs), as * well as some auxiliary data ushc as draw flags and team index. * - * @tparam number|{number,...} featureIDs - * @number attrID - * @number[opt] teamIdOpt - * @number[opt] elementOffset - * @treturn {number,number,number,number} instanceData - * @treturn number elementOffset - * @treturn attrID + * @param featureIDs number|number[] + * @param attrID integer + * @param teamIdOpt integer? + * @param elementOffset integer? + * @return [number,number,number,number] instanceData + * @return integer elementOffset + * @return integer attrID */ size_t LuaVBOImpl::InstanceDataFromFeatureIDs(int id, int attrID, sol::optional elemOffsetOpt) { @@ -1308,13 +1350,13 @@ size_t LuaVBOImpl::InstanceDataFromFeatureIDs(const sol::stack_table& ids, int a /*** * * @function VBO:MatrixDataFromProjectileIDs - * @tparam number|{number,...} projectileIDs - * @number attrID - * @number[opt] teamIdOpt - * @number[opt] elementOffset - * @treturn {number, ...} matDataVec 4x4 matrix - * @treturn number elemOffset - * @treturn number|{number,number,number,number} attrID + * @param projectileIDs integer|integer[] + * @param attrID integer + * @param teamIdOpt integer? + * @param elementOffset integer? + * @return number[] matDataVec 4x4 matrix + * @return integer elemOffset + * @return integer|[integer,integer,integer,integer] attrID */ size_t LuaVBOImpl::MatrixDataFromProjectileIDs(int id, int attrID, sol::optional elemOffsetOpt) { @@ -1395,12 +1437,12 @@ int LuaVBOImpl::BindBufferRangeImpl(GLuint bindingIndex, const sol::optional elemOffsetOpt, const sol::optional elemCountOpt, const sol::optional targetOpt) { @@ -1411,11 +1453,11 @@ int LuaVBOImpl::BindBufferRange(const GLuint index, const sol::optional ele /*** * * @function VBO:UnbindBufferRange - * @tparam number index - * @number[opt] elementOffset - * @number[opt] elementCount - * @number[opt] target glEnum - * @treturn number bindingIndex when successful, -1 otherwise + * @param index integer + * @param elementOffset integer? + * @param elementCount number? + * @param target number? glEnum + * @return number bindingIndex when successful, -1 otherwise */ int LuaVBOImpl::UnbindBufferRange(const GLuint index, const sol::optional elemOffsetOpt, const sol::optional elemCountOpt, const sol::optional targetOpt) { @@ -1426,7 +1468,7 @@ int LuaVBOImpl::UnbindBufferRange(const GLuint index, const sol::optional e /*** Logs the definition of the VBO to the console * * @function VBO:DumpDefinition - * @treturn nil + * @return nil */ void LuaVBOImpl::DumpDefinition() { diff --git a/rts/Lua/LuaVFS.cpp b/rts/Lua/LuaVFS.cpp index 07769bd976..b0acbc4ac4 100644 --- a/rts/Lua/LuaVFS.cpp +++ b/rts/Lua/LuaVFS.cpp @@ -26,7 +26,6 @@ /****************************************************************************** * Virtual File System - * @module VFS * * @see rts/Lua/LuaVFS.cpp ******************************************************************************/ diff --git a/rts/Lua/LuaZip.cpp b/rts/Lua/LuaZip.cpp index 6282e1317d..daf209b7d6 100644 --- a/rts/Lua/LuaZip.cpp +++ b/rts/Lua/LuaZip.cpp @@ -3,7 +3,6 @@ /****************************************************************************** * LuaZip - * @module LuaZip * * @see rts/Lua/LuaZip.cpp ******************************************************************************/ diff --git a/rts/Lua/library/.luarc.json b/rts/Lua/library/.luarc.json new file mode 100644 index 0000000000..dbc32260ee --- /dev/null +++ b/rts/Lua/library/.luarc.json @@ -0,0 +1,41 @@ +// This file is used by lua-language-server for generating docs for the site. +// See .github/workflows/publish-site.yml +{ + "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json", + "runtime.version": "Lua 5.1", + "completion.requireSeparator": "/", + // Exclude builtin Lua libraries as a workaround for + // LuaLS/lua-language-server#2977. + "runtime.builtin": { + "basic": "disable", + "bit": "disable", + "bit32": "disable", + "builtin": "disable", + "coroutine": "disable", + "debug": "disable", + "ffi": "disable", + "io": "disable", + "jit": "disable", + "math": "disable", + "os": "disable", + "package": "disable", + "string": "disable", + "table": "disable", + "table.clear": "disable", + "table.new": "disable", + "utf8": "disable" + }, + "workspace.ignoreDir": [ + "cont", + "lib" + ], + "runtime.path": [ + "?", + "?.lua" + ], + "runtime.special": { + "VFS.Include": "require", + "include": "require", + "shard_include": "require" + } +} diff --git a/rts/Lua/library/Types.lua b/rts/Lua/library/Types.lua new file mode 100644 index 0000000000..7224669b25 --- /dev/null +++ b/rts/Lua/library/Types.lua @@ -0,0 +1,120 @@ +---@meta + +-------------------------------------------------------------------------------- +-- Vectors +-------------------------------------------------------------------------------- + +---Cartesian triple (XYZ) +--- +---@class xyz +---@field x number +---@field y number +---@field z number + +---@alias float3 xyz + +-------------------------------------------------------------------------------- +-- Color +-------------------------------------------------------------------------------- + +---Color triple (RGB) +--- +---@class rgb +---@field r number +---@field g number +---@field b number + +---Color quadruple (RGBA) +--- +---@class rgba +---@field r number +---@field g number +---@field b number +---@field a number + +-------------------------------------------------------------------------------- +-- Camera +-------------------------------------------------------------------------------- + +---@alias CameraMode +---| 0 # fps +---| 1 # ta +---| 2 # spring +---| 3 # rot +---| 4 # free +---| 5 # ov +---| 6 # dummy + +---Parameters for camera state +--- +---@class CameraState +--- +---Highly dependent on the type of the current camera controller +---@field name "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy" +---@field mode CameraMode The camera mode +---@field fov number? +---@field px number? Position X of the ground point in screen center +---@field py number? Position Y of the ground point in screen center +---@field pz number? Position Z of the ground point in screen center +---@field dx number? Camera direction vector X +---@field dy number? Camera direction vector Y +---@field dz number? Camera direction vector Z +---@field rx number? Camera rotation angle on X axis (spring) +---@field ry number? Camera rotation angle on Y axis (spring) +---@field rz number? Camera rotation angle on Z axis (spring) +---@field angle number? Camera rotation angle on X axis (aka tilt/pitch) (ta) +---@field flipped number? -1 for when south is down, 1 for when north is down (ta) +---@field dist number? Camera distance from the ground (spring) +---@field height number? Camera distance from the ground (ta) +---@field oldHeight number? Camera distance from the ground, cannot be changed (rot) + +-------------------------------------------------------------------------------- +-- Commands +-------------------------------------------------------------------------------- + +---Parameters for command options +--- +---@class CommandOptions +---@field coded integer +---@field alt boolean Alt key pressed +---@field ctrl boolean Ctrl key pressed +---@field shift boolean Shift key pressed +---@field right boolean Right mouse key pressed +---@field meta boolean Meta key pressed (space) +---@field internal boolean + +---Used when assigning multiple commands at once +--- +---@class Command +---@field cmdID integer +---@field params number[]? +---@field options CommandOptions? + +---Command Description +--- +---Contains data about a command. +--- +---@class CommandDescription +---@field id integer? +---@field type integer? +---@field name string? +---@field action string? +---@field tooltip string? +---@field texture string? +---@field cursor string? +---@field queueing boolean? +---@field hidden boolean? +---@field disabled boolean? +---@field showUnique boolean? +---@field onlyTexture boolean? +---@field params table? + +-------------------------------------------------------------------------------- +-- Resources +-------------------------------------------------------------------------------- + +---@alias ResourceName "metal"|"energy"|"m"|"e" + +---@alias StorageName "metalStorage"|"energyStorage"|"ms"|"es" + +---@alias ResourceUsage table \ No newline at end of file