diff --git a/.github/workflows/publish-site.yml b/.github/workflows/publish-site.yml
index efac668ec8..72c83724c3 100644
--- a/.github/workflows/publish-site.yml
+++ b/.github/workflows/publish-site.yml
@@ -13,7 +13,7 @@ env:
LUA_DOC_EXTRACTOR_SOURCE_REF: "https://github.com/${{ github.repository }}/blob/${{ github.sha }}"
HUGO_VERSION: "0.147.9"
LUA_DOC_EXTRACTOR_VERSION: "3"
- EMMYLUA_DOC_CLI_VERSION: "0.8.2"
+ EMMYLUA_DOC_CLI_VERSION: "0.9.0"
JQ_VERSION: "1.8.0"
7Z_VERSION: "24.09"
RUBY_VERSION: "3.3"
diff --git a/doc/site/assets/css/custom.css b/doc/site/assets/css/custom.css
index 05b77dc536..a53a919139 100644
--- a/doc/site/assets/css/custom.css
+++ b/doc/site/assets/css/custom.css
@@ -2,6 +2,10 @@
grid-column: span 1 / span 1;
}
+.col-span-2 {
+ grid-column: span 2 / span 2;
+}
+
.grid-cols-2 {
grid-template-columns: max-content minmax(0, 1fr);
}
@@ -30,6 +34,14 @@
margin-top: .5rem !important;
}
+.ml-05 {
+ margin-top: .5rem !important;
+}
+
+.right {
+ float: right;
+}
+
.mt-1 {
margin-top: 1rem;
}
@@ -60,7 +72,7 @@
margin-bottom: .5rem !important;
}
- h5, h6, p, ul, .hextra-code-block {
+ h5, h6, p, ul, ol, .hextra-code-block {
margin-top: .5rem !important;
}
diff --git a/doc/site/docgen/generator.rb b/doc/site/docgen/generator.rb
index fc7d58f15b..4c367b5334 100644
--- a/doc/site/docgen/generator.rb
+++ b/doc/site/docgen/generator.rb
@@ -10,7 +10,6 @@ def a(name)
end
class Member
- @@other_matcher = Regexp.compile('\@\*(\w+)\*( (.*))?')
@@refs = Set.new
def self.refs; @@refs; end
@@ -26,13 +25,15 @@ def initialize(attributes, parent = nil)
end
def generate_sidebar_entry()
+ return if helper or type == :alias
+
entries = if fields.empty? or children.empty?
""
else
"{name = 'Fields', link = '##{ref}_fields', ref = '#{ref}_fields'}, "
end
- entries += children.map(&:generate_sidebar_entry).join(', ')
+ entries += children.map(&:generate_sidebar_entry).compact.join(', ')
"{name = '#{name}', link = '##{ref}', ref = '#{ref}', entries = [#{entries}]}"
end
@@ -49,6 +50,16 @@ def generate_fields(member_type = nil)
self.fields.map(&:generate).join("\n")
end
+ def generate_see()
+ return if see.empty?
+
+ <<~EOF
+ See:
+
+ #{see.map {|s| "- #{s}"}.join("\n")}
+ EOF
+ end
+
def generate(internal_type = nil)
internal_type = internal_type || self.type
@@ -72,7 +83,7 @@ def push_to_refs()
@@refs.add(self.ref)
end
- @@deep_type_ref_matcher = Regexp.new('[^\s\(\)\[\]\|\?&;]+')
+ @@deep_type_ref_matcher = Regexp.new('[\w\.]+')
def self.replace_deep_type_refs(value)
return value if not value&.is_a?(String)
@@ -84,7 +95,7 @@ def self.replace_deep_type_refs(value)
end
end
- @@ref_matcher = Regexp.new("`([^`]*)`")
+ @@ref_matcher = Regexp.new(%q((\A|[^`])`([^`]+)`))
def self.replace_refs(value)
return value if not value&.is_a?(String)
@@ -100,12 +111,12 @@ def self.replace_refs(value)
.each {|m| value.gsub!("`#{m}`", a(m)) }
value
.gsub(@@ref_matcher) do |match|
- "#{self.replace_deep_type_refs($1)}"
+ "#{$1}#{self.replace_deep_type_refs($2)}"
end
end
def process_refs()
- self.see = a(see) if @@refs.include?(see)
+ self.see = see.map {|s| @@refs.include?(s) ? a(s) : s }
self.description = Member.replace_refs(self.description)
@@ -113,12 +124,20 @@ def process_refs()
p["typeref"] = Member.replace_deep_type_refs(p["typ"])
p["ref"] = "#{full_name}-params.#{p["name"]}"
p["desc"] = Member.replace_refs(p["desc"])
+
+ segments = (p["desc"] || "").strip.split("\n")
+ p["summary"] = segments.slice!(0)&.strip
+ p["short_desc"] = segments.empty? ? nil : segments.join("\n")
end
returns&.each do |p|
p["typeref"] = Member.replace_deep_type_refs(p["typ"])
p["ref"] = "#{full_name}-returns.#{p["name"]}"
p["desc"] = Member.replace_refs(p["desc"])
+
+ segments = (p["desc"] || "").strip.split("\n")
+ p["summary"] = segments.slice!(0)&.strip
+ p["short_desc"] = segments.empty? ? nil : segments.join("\n")
end
self.typeref = Member.replace_deep_type_refs(self.typ)
@@ -128,7 +147,7 @@ def process_refs()
segments = self.description.strip.split("\n")
self.summary = segments.slice!(0)&.strip
- self.short_description = segments.join("\n")
+ self.short_description = segments.join("\n") if not segments.empty?
end
children.each(&:process_refs)
@@ -151,15 +170,12 @@ def process_members()
end
def self.compare(m1, m2)
- helper1 = m1.custom["x_helper"]
- helper2 = m2.custom["x_helper"]
-
# Tagged helpers should be at the utmost bottom
- if helper1 && helper1 == helper2
+ if m1.helper && m1.helper == m2.helper
0
- elsif helper1
+ elsif m1.helper
1
- elsif helper2
+ elsif m2.helper
-1
elsif m1.type == m2.type
m1.full_name <=> m2.full_name
@@ -214,27 +230,17 @@ def initialize_attributes(parent)
end
def extract_custom_tags()
- other = self.other
-
- if !other
- self.custom = {}
- self.section = nil
-
- return
- end
-
- custom = other.split("\n\n").reduce({}) do |acc, el|
- name, _, value = el.match(@@other_matcher).captures
-
- if name
- acc[name] = value || true
- end
+ self.tags = (self.tag_content || {}).reduce({}) do |acc, el|
+ acc[el["tag_name"]] ||= []
+ acc[el["tag_name"]].push(el["content"])
acc
end
- self.custom = custom
- self.section = custom["section"]
+
+ self.section = tags["x_section"]
+ self.helper = tags["x_helper"]
+ self.see = tags["see"] || []
end
end
@@ -245,14 +251,11 @@ class Generator
def self.compare_members(m1, m2)
# helpers to the bottom
- helper1 = m1.custom["x_helper"]
- helper2 = m2.custom["x_helper"]
-
- if helper1 && (helper1 == helper2)
+ if m1.helper && (m1.helper == m2.helper)
return 0
- elsif helper1
+ elsif m1.helper
return 1
- elsif helper2
+ elsif m2.helper
return -1
end
@@ -291,7 +294,7 @@ def generate
# ## Table of Contents
#
# #{@globals.map { |el| el.generate(:definition) }.join("\n")}
- entries = @globals.map(&:generate_sidebar_entry).join(',')
+ entries = @globals.map(&:generate_sidebar_entry).compact.join(',')
<<~EOF
+++
diff --git a/doc/site/docgen/templates.rb b/doc/site/docgen/templates.rb
index 2b7287d071..6be2a27e1c 100644
--- a/doc/site/docgen/templates.rb
+++ b/doc/site/docgen/templates.rb
@@ -1,7 +1,8 @@
-def md(string)
+def md(string, inline = false)
string ||= ""
string = string.gsub('"', '\"').split("\n").join('" "')
- %Q({{< md "#{string}" >}})
+ tag = inline ? "md_inline" : "md"
+ %Q({{< #{tag} "#{string}" >}})
end
H_TEMPLATE = ERB.new <<~'EOF'
@@ -28,38 +29,42 @@ class Member < OpenStruct
Deprecated<%= ": #{deprecation_reason}" if deprecation_reason %>
<% end %>
- <% if see %>
- See <%= see %>
- <% end %>
+ <%= generate_see %>
<%= generate_fields() %>
EOF
@@function_template = ERB.new <<~'EOF'
<%= h(dom_level, full_name + ' (' + type.to_s + (" overload #{overload_index}" if overload_index).to_s + ')', ref) %>
- <%= md description %>
+ <%= description %>
<% if deprecated %>
Deprecated<%= ": #{deprecation_reason}" if deprecation_reason %>
<% end %>
- <% if see %>
- See <%= see %>
- <% end %>
+ <%= generate_see %>
```lua
- <%= full_name %>(<%= params.map {|p| p["name"] == "..." ? "[#{p["typ"]}, ]*" : p["typ"] }.join(", ") unless params.empty?
- %>) -> <% if returns.empty? %>nil<% else %><%= returns.map {|p| p["name"] == "..." ? "[#{p["typ"]}, ]*" : p["typ"] }.join(", ") %><% end %>
+ <%= full_name %>(<%= params.map {|p| p["name"] == "..." ? "[#{p["typ"]}, ]*" : p["typ"] }.join(", ") unless params.empty?
+ %>) -> <% if returns.empty? %>nil<% else %><%= returns.map {|p| p["name"] == "..." ? "[#{p["typ"]}, ]*" : p["typ"] }.join(", ") %><% end %>
```
<% if not params.empty? %>
<%= h(dom_level + 1, "Parameters", "#{ref}_arguments") %>
-
+
<% params.each do |param| %>
- <%= param["typeref"] %>"><%= param["name"] %>" class="hx-absolute -hx-mt-20">- <%= md(param["desc"]) %>
+ - ">
+
<%= param["typeref"] %>" class="hx-absolute -hx-mt-20">"><%= param["name"] %>
+
+
+
+ <% if param["short_desc"].nil? %>
+ - <%= md(param["summary"], true) %>
+ <% else %>
+ - <%= md(param["desc"]) %>
+ <% end %>
<% end %>
<% end %>
@@ -67,10 +72,17 @@ class Member < OpenStruct
<% if not returns.empty? %>
<%= h(dom_level + 1, "Returns", "#{ref}_returns") %>
-
- <% returns.each do |return_value| %>
- <%= return_value["typeref"] %>"><%= return_value["name"] %>" class="hx-absolute -hx-mt-20">- <%= md(return_value["desc"]) %>
+
+ <% returns.each do |param| %>
+ - ">
+
<%= param["typeref"] %>"><%= param["name"] %>" class="hx-absolute -hx-mt-20">
+
+
+ <% if param["short_desc"].nil? %>
+ - <%= md(param["summary"], true) %>
+ <% else %>
+ - <%= md(param["desc"]) %>
+ <% end %>
<% end %>
<% end %>
@@ -84,10 +96,7 @@ class Member < OpenStruct
Deprecated<%= ": #{deprecation_reason}" if deprecation_reason %>
<% end %>
- <% if see %>
-
- See <%= see %>
- <% end %>
+ <%= generate_see %>
<% if not children.empty? %>
<%= h(dom_level + 1, "Members", "#{ref}_members") %>
@@ -98,7 +107,7 @@ class Member < OpenStruct
<% if not fields.empty? %>
<%= h(dom_level + 1, "Fields", "#{ref}_fields") %>
- <%= generate_fields() %>
+ <%= generate_fields() %>
<% end %>
EOF
@@ -115,10 +124,7 @@ class Member < OpenStruct
Deprecated<%= ": #{deprecation_reason}" if deprecation_reason %>
<% end %>
- <% if see %>
-
- See <%= see %>
- <% end %>
+ <%= generate_see %>
<% if not children.empty? %>
<%= h(dom_level + 1, "Members", "#{ref}_members") %>
@@ -129,7 +135,7 @@ class Member < OpenStruct
<% if not fields.empty? %>
<%= h(dom_level + 1, "Fields", "#{ref}_fields") %>
- <%= generate_fields() %>
+ <%= generate_fields() %>
<% end %>
EOF
@@ -141,10 +147,7 @@ class Member < OpenStruct
Deprecated<%= ": #{deprecation_reason}" if deprecation_reason %>
<% end %>
- <% if see %>
-
- See <%= see %>
- <% end %>
+ <%= generate_see %>
<% if not children.empty? %>
<%= h(dom_level + 1, "Members", "#{ref}_members") %>
@@ -155,7 +158,7 @@ class Member < OpenStruct
<% if not fields.empty? %>
<%= h(dom_level + 1, "Fields", "#{ref}_fields") %>
- <%= generate_fields() %>
+ <%= generate_fields() %>
<% end %>
EOF
@@ -172,14 +175,11 @@ class Member < OpenStruct
Deprecated<%= ": #{deprecation_reason}" if deprecation_reason %>
<% end %>
- <% if see %>
-
- See <%= see %>
- <% end %>
+ <%= generate_see %>
EOF
@@definition_template = ERB.new <<~'EOF'
- <% if type != :alias && !custom["helper"] %>
+ <% if type != :alias && !helper %>
- <% if type != :enum && !custom["no_toc_contents"] %>
+ <% if type != :enum %>
<%= generate_children(:definition_field) %>
@@ -201,8 +201,16 @@ class Member < OpenStruct
EOF
@@field_template = ERB.new <<~'EOF'
- <%= literal || typeref %> <%= name %>- <%= md(description) %>
+ -
+
<%= literal || typeref %>
+ <%= name %>
+
+
+ <% if short_description.nil? %>
+ - <%= md(summary, true) %>
+ <% else %>
+ - <%= md(description) %>
+ <% end %>
EOF
@@templates = {
diff --git a/doc/site/layouts/shortcodes/md_inline.html b/doc/site/layouts/shortcodes/md_inline.html
new file mode 100644
index 0000000000..f9c93cda1a
--- /dev/null
+++ b/doc/site/layouts/shortcodes/md_inline.html
@@ -0,0 +1 @@
+{{ (delimit .Params "\n") | .Page.RenderString }}
diff --git a/doc/site/mise.toml b/doc/site/mise.toml
index 231c3713de..63a48123c8 100644
--- a/doc/site/mise.toml
+++ b/doc/site/mise.toml
@@ -1,11 +1,12 @@
[tools]
+ "cargo:https://github.com/EmmyLuaLs/emmylua-analyzer-rust" = { version = "rev:9924098", crate = "emmylua_doc_cli" }
# We only install tools required for each task on each task, unless all tasks use a tool here
# For CI when we need to install and cache all tools, see mise.ci.toml
[env]
HUGO_VERSION = "0.147.9"
LUA_DOC_EXTRACTOR_VERSION = "3" # lua_library lua_check
- EMMYLUA_DOC_CLI_VERSION = "0.8.2" # lua_pages lua_library lua_check
+ EMMYLUA_DOC_CLI_VERSION = "rev:9924098" # lua_pages lua_library lua_check
LUA_LANGUAGE_SERVER_VERSION = "3.15.0" # lua_check
JQ_VERSION = "1.8.0" # binary_pages
7Z_VERSION = "24.09" # binary_pages
@@ -42,7 +43,6 @@
[tasks.lua_json]
description = "Generate Lua JSON export"
- tools."cargo:emmylua_doc_cli" = "{{env.EMMYLUA_DOC_CLI_VERSION}}"
depends = ["lua_library"]
dir = "../../"
run = "emmylua_doc_cli -f json -i $RECOIL_LUA_LIBRARY_DIR -o {{vars.site_dir}}/data"
diff --git a/rts/Lua/LuaConstCMD.cpp b/rts/Lua/LuaConstCMD.cpp
index e96dbe27c1..e01d6e0277 100644
--- a/rts/Lua/LuaConstCMD.cpp
+++ b/rts/Lua/LuaConstCMD.cpp
@@ -21,7 +21,7 @@
* @see Spring.GiveOrderToUnit
* @see Spring.GiveOrderArrayToUnitArray
* @see Spring.GetUnitCurrentCommand
- * @see Callins:AllowCommand
+ * @see SyncedCallins:AllowCommand
* @enum CMD
*/
diff --git a/rts/Lua/LuaConstGame.cpp b/rts/Lua/LuaConstGame.cpp
index a4155904cc..96e7794f69 100644
--- a/rts/Lua/LuaConstGame.cpp
+++ b/rts/Lua/LuaConstGame.cpp
@@ -99,7 +99,7 @@
* ["air"] = 30
* }
* ```
- * @field armorTypes table (bidirectional)
+ * @field armorTypes table (bidirectional)
* ```lua
* example: {
* [1] = amphibious, [2] = anniddm, [3] = antibomber,
diff --git a/rts/Lua/LuaEncoding.cpp b/rts/Lua/LuaEncoding.cpp
index fb2b73cb0f..3f6c25fab8 100644
--- a/rts/Lua/LuaEncoding.cpp
+++ b/rts/Lua/LuaEncoding.cpp
@@ -63,7 +63,7 @@ int LuaEncoding::DecodeBase64(lua_State* L)
* @function Encoding.EncodeBase64
*
* @param text string Text to encode
- * @param stripPadding? boolean Remove padding (`=` characters) at the end when 'true'. Defaults to `true`.
+ * @param stripPadding? boolean (Default: `true`) Remove padding (`=` characters) at the end when 'true'.
* @return string encoded Encoded text
*/
int LuaEncoding::EncodeBase64(lua_State* L)
diff --git a/rts/Lua/LuaFonts.cpp b/rts/Lua/LuaFonts.cpp
index 34d53693f7..676341c007 100644
--- a/rts/Lua/LuaFonts.cpp
+++ b/rts/Lua/LuaFonts.cpp
@@ -375,7 +375,7 @@ int LuaFonts::PrintWorld(lua_State* L)
* Also allows disabling automatic setting of the blend mode. Otherwise the font will always print
* with `BlendFunc(GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA)`.
- * @param userDefinedBlending boolean? When `true` doesn't set the gl.BlendFunc automatically. Defaults to `false`.
+ * @param userDefinedBlending boolean? (Default: `false`) When `true` doesn't set the `gl.BlendFunc` automatically.
*
* @see gl.BlendFunc
* @see gl.BlendFuncSeparate
@@ -403,8 +403,8 @@ int LuaFonts::End(lua_State* L)
*
* @function LuaFont:SubmitBuffered
*
- * @param noBillboarding boolean? When `false` sets 3d billboard mode. Defaults to `true`.
- * @param userDefinedBlending boolean? When `true` doesn't set the gl.BlendFunc automatically. Defaults to `false`.
+ * @param noBillboarding boolean? (Default: `false`) When `false` sets 3d billboard mode.
+ * @param userDefinedBlending boolean? (Default: `false`) When `true` doesn't set the gl.BlendFunc automatically.
*
* @see gl.BlendFunc
* @see gl.BlendFuncSeparate
diff --git a/rts/Lua/LuaOpenGL.cpp b/rts/Lua/LuaOpenGL.cpp
index 46ff28917f..f580066101 100644
--- a/rts/Lua/LuaOpenGL.cpp
+++ b/rts/Lua/LuaOpenGL.cpp
@@ -1339,7 +1339,7 @@ int LuaOpenGL::DrawMiniMap(lua_State* L)
* Also allows disabling automatic setting of the blend mode. Otherwise the font will always print
* with `BlendFunc(GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA)`.
*
- * @param userDefinedBlending boolean? When `true` doesn't set the gl.BlendFunc automatically. Defaults to `false`.
+ * @param userDefinedBlending boolean? (Default: `false`) When `true` doesn't set the gl.BlendFunc automatically.
*
* @see gl.BlendFunc
* @see gl.BlendFuncSeparate
diff --git a/rts/Lua/LuaSyncedCtrl.cpp b/rts/Lua/LuaSyncedCtrl.cpp
index 52ad4e6dee..d63a8ea50d 100644
--- a/rts/Lua/LuaSyncedCtrl.cpp
+++ b/rts/Lua/LuaSyncedCtrl.cpp
@@ -1103,24 +1103,21 @@ int LuaSyncedCtrl::AddTeamResource(lua_State* L)
return 0;
}
-/***
- * Consumes metal or energy resources of the specified team.
+/*** Consumes resource of the specified team (single)
*
* @function Spring.UseTeamResource
* @param teamID integer
- * @param type ResourceName Resource type.
+ * @param type "m"|"e" 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.
+ * @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.
+
+/*** Consumes resource of the specified team (table)
*
* @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.
+ * @param amount table<"m"|"e",number> keys are: "[m|e]" metal | energy. Values are amounts
+ * @return boolean hadEnough True if enough of the resource type(s) were available and was consumed, otherwise false.
*/
int LuaSyncedCtrl::UseTeamResource(lua_State* L)
{
@@ -2062,7 +2059,7 @@ int LuaSyncedCtrl::SetUnitResourcing(lua_State* L)
/***
* @function Spring.SetUnitStorage
* @param unitID integer
- * @param res ResourceUsage keys are: "[m|e]" metal | energy. Values are amounts
+ * @param res table keys are: "[m|e]" metal | energy. Values are amounts
*/
int LuaSyncedCtrl::SetUnitStorage(lua_State* L)
{
@@ -3243,7 +3240,7 @@ int LuaSyncedCtrl::SetUnitShieldRechargeDelay(lua_State* L)
/***
* @function Spring.SetUnitFlanking
* @param unitID integer
- * @param type string "dir"|"minDamage"|"maxDamage"|"moveFactor"|"mode"
+ * @param type "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"
@@ -3290,8 +3287,7 @@ int LuaSyncedCtrl::SetUnitFlanking(lua_State* L)
/***
* @function Spring.SetUnitPhysicalStateBit
* @param unitID integer
- * @param Physical number[bit] state bit
- * @return nil
+ * @param bit integer Physical state bit
*/
int LuaSyncedCtrl::SetUnitPhysicalStateBit(lua_State* L)
{
@@ -3309,7 +3305,7 @@ int LuaSyncedCtrl::SetUnitPhysicalStateBit(lua_State* L)
/***
* @function Spring.GetUnitPhysicalState
* @param unitID integer
- * @return number Unit's PhysicalState bitmask
+ * @return number bitmask Unit's PhysicalState bitmask
*/
int LuaSyncedCtrl::GetUnitPhysicalState(lua_State* L)
{
@@ -3335,7 +3331,7 @@ int LuaSyncedCtrl::SetUnitFuel(lua_State* L) { return 0; } // FIXME: DELETE ME
*
* @param unitID integer
* @param neutral boolean
- * @return nil|boolean setNeutral
+ * @return boolean? setNeutral
*/
int LuaSyncedCtrl::SetUnitNeutral(lua_State* L)
{
@@ -4265,7 +4261,7 @@ int LuaSyncedCtrl::AddUnitResource(lua_State* L)
/***
* @function Spring.UseUnitResource
* @param unitID integer
- * @param resources ResourceUsage
+ * @param resources table<"m"|"e",number> keys are: "[m|e]" metal | energy. Values are amounts
* @return boolean? okay
*/
int LuaSyncedCtrl::UseUnitResource(lua_State* L)
diff --git a/rts/Lua/LuaSyncedRead.cpp b/rts/Lua/LuaSyncedRead.cpp
index 241d7e9d69..857be969b8 100644
--- a/rts/Lua/LuaSyncedRead.cpp
+++ b/rts/Lua/LuaSyncedRead.cpp
@@ -3403,10 +3403,10 @@ static int GetUnitTableCentroid(lua_State *const L, const int indexWithinTable,
* Returns nil for an empty array
*
* @function Spring.GetUnitArrayCentroid
- * @param units table { unitID, unitID, ... }
- * @return number centerX
- * @return number centerY
- * @return number centerZ
+ * @param units integer[]
+ * @return number? centerX
+ * @return number? centerY
+ * @return number? centerZ
*/
int LuaSyncedRead::GetUnitArrayCentroid(lua_State* L)
{
@@ -3418,10 +3418,10 @@ int LuaSyncedRead::GetUnitArrayCentroid(lua_State* L)
* Returns nil for an empty map
*
* @function Spring.GetUnitMapCentroid
- * @param units table { [unitID] = true, [unitID] = true, ... }
- * @return number centerX
- * @return number centerY
- * @return number centerZ
+ * @param units table { [unitID] = true, [unitID] = true, ... }
+ * @return number? centerX
+ * @return number? centerY
+ * @return number? centerZ
*/
int LuaSyncedRead::GetUnitMapCentroid(lua_State* L)
{
diff --git a/rts/Lua/LuaUnsyncedRead.cpp b/rts/Lua/LuaUnsyncedRead.cpp
index 7a9fa2f7e1..c4ea5d19be 100644
--- a/rts/Lua/LuaUnsyncedRead.cpp
+++ b/rts/Lua/LuaUnsyncedRead.cpp
@@ -4547,16 +4547,10 @@ int LuaUnsyncedRead::GetLogSections(lua_State* L) {
}
-/******************************************************************************
- * Decals
- * @section decals
-******************************************************************************/
-
-
/***
*
* @function Spring.GetAllGroundDecals
- *
+ * @x_section decals
* @return number[] decalIDs
*/
int LuaUnsyncedRead::GetAllGroundDecals(lua_State* L)
@@ -4590,6 +4584,7 @@ int LuaUnsyncedRead::GetAllGroundDecals(lua_State* L)
/***
*
* @function Spring.GetGroundDecalMiddlePos
+ * @x_section decals
* @param decalID integer
* @return number? posX
* @return number posZ
@@ -4612,6 +4607,7 @@ int LuaUnsyncedRead::GetGroundDecalMiddlePos(lua_State* L)
*
* @function Spring.GetGroundDecalQuadPos
* @param decalID integer
+ * @x_section decals
* @return number? posTL.x
* @return number posTL.z
* @return number posTR.x
@@ -4645,6 +4641,7 @@ int LuaUnsyncedRead::GetGroundDecalQuadPos(lua_State* L)
*
* @function Spring.GetGroundDecalSizeAndHeight
* @param decalID integer
+ * @x_section decals
* @return number? sizeX
* @return number sizeY
* @return number projCubeHeight
@@ -4668,6 +4665,7 @@ int LuaUnsyncedRead::GetGroundDecalSizeAndHeight(lua_State* L)
/***
*
* @function Spring.GetGroundDecalRotation
+ * @x_section decals
* @param decalID integer
* @return number? rotation Rotation in radians.
*/
@@ -4687,6 +4685,7 @@ int LuaUnsyncedRead::GetGroundDecalRotation(lua_State* L)
/***
*
* @function Spring.GetGroundDecalTexture
+ * @x_section decals
* @param decalID integer
* @param isMainTex boolean? (Default: `true`) If `false`, return the normal/glow map.
* @return string? texture
@@ -4702,6 +4701,7 @@ int LuaUnsyncedRead::GetGroundDecalTexture(lua_State* L)
/***
*
* @function Spring.GetGroundDecalTextures
+ * @x_section decals
* @param isMainTex boolean? (Default: `true`) If `false`, return the texture for normal/glow maps.
* @return string[] textureNames All textures on the atlas and available for use in `SetGroundDecalTexture`.
* @see Spring.GetGroundDecalTexture
@@ -4718,6 +4718,7 @@ int LuaUnsyncedRead::GetGroundDecalTextures(lua_State* L)
/***
*
* @function Spring.SetGroundDecalTextureParams
+ * @x_section decals
* @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.
@@ -4739,6 +4740,7 @@ int LuaUnsyncedRead::GetGroundDecalTextureParams(lua_State* L)
/***
*
* @function Spring.GetGroundDecalAlpha
+ * @x_section decals
* @param decalID integer
* @return number? alpha Between 0 and 1
* @return number alphaFalloff Between 0 and 1, per second
@@ -4762,6 +4764,7 @@ int LuaUnsyncedRead::GetGroundDecalAlpha(lua_State* L)
*
* If all three equal 0, the decal follows the normals of ground at midpoint
*
+ * @x_section decals
* @param decalID integer
* @return number? normal.x
* @return number normal.y
@@ -4781,11 +4784,12 @@ int LuaUnsyncedRead::GetGroundDecalNormal(lua_State* L)
return 3;
}
-/***
+/*** Get the current tint of a ground decal.
+ *
+ * A color of (0.5, 0.5, 0.5, 0.5) is effectively no tint
*
* @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
+ * @x_section decals
* @param decalID integer
* @return number? tintR
* @return number tintG
@@ -4808,10 +4812,10 @@ int LuaUnsyncedRead::GetGroundDecalTint(lua_State* L)
return 4;
}
-/***
+/*** Get other parameters for a ground decal
*
* @function Spring.GetGroundDecalMisc
- * Returns less important parameters of a ground decal
+ * @x_section decals
* @param decalID integer
* @return number? dotElimExp
* @return number refHeight
@@ -4834,12 +4838,12 @@ int LuaUnsyncedRead::GetGroundDecalMisc(lua_State* L)
return 5;
}
-/***
- *
- * @function Spring.GetGroundDecalCreationFrame
+/*** Get the creation frame settings for a decal
*
* Min can be not equal to max for "gradient" style decals, e.g. unit tracks
*
+ * @function Spring.GetGroundDecalCreationFrame
+ * @x_section decals
* @param decalID integer
* @return number? creationFrameMin
* @return number creationFrameMax
@@ -4860,6 +4864,7 @@ int LuaUnsyncedRead::GetGroundDecalCreationFrame(lua_State* L)
/***
* @function Spring.GetGroundDecalOwner
+ * @x_section decals
* @param decalID integer
* @return integer? value If owner is a unit, then this is `unitID`, if owner is
* a feature it is `featureID + MAX_UNITS`. If there is no owner, then `nil`.
@@ -4882,6 +4887,7 @@ int LuaUnsyncedRead::GetGroundDecalOwner(lua_State* L)
/***
*
* @function Spring.GetGroundDecalType
+ * @x_section decals
* @param decalID integer
* @return "explosion"|"plate"|"lua"|"track"|"unknown"|nil type
*/
diff --git a/rts/Lua/LuaVBOImpl.cpp b/rts/Lua/LuaVBOImpl.cpp
index 5a928b21dc..10823f012c 100644
--- a/rts/Lua/LuaVBOImpl.cpp
+++ b/rts/Lua/LuaVBOImpl.cpp
@@ -109,7 +109,6 @@ inline void LuaVBOImpl::InstanceBufferCheckAndFormatCheck(int attrID, const char
/***
*
* @function VBO:Delete
- * @return nil
*/
void LuaVBOImpl::Delete()
{
@@ -459,25 +458,23 @@ bool LuaVBOImpl::DefineElementArray(const sol::optional attribDefAr
/***
* @class VBOAttributeDef
* @x_helper
- *
- * @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? (Default: `attr#` where `#` is `id`)
- *
+ *
+ * @field id integer?
+ *
* 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
+ *
+ * @field name string? (Default: `attr#` where `#` is `id`)
+ *
+ * Defaults 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 GL? (Default: `GL.FLOAT`) The datatype of this element.
+ *
+ * @field size integer?
*
* Accepts the following:
* - `GL.BYTE`
@@ -487,11 +484,13 @@ bool LuaVBOImpl::DefineElementArray(const sol::optional attribDefAr
* - `GL.INT`
* - `GL.UNSIGNED_INT`
* - `GL.FLOAT`
- *
- * @field normalized boolean? (Defaults: `false`)
- *
+ *
+ * @field type GL? (Default: `GL.FLOAT`) The datatype of this element.
+ *
* It's possible to submit normals without normalizing them first, normalized
* will make sure data is normalized.
+ *
+ * @field normalized boolean? (Defaults: `false`)
*/
/***
@@ -523,13 +522,8 @@ bool LuaVBOImpl::DefineElementArray(const sol::optional attribDefAr
*
* @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.
- *
+ * @param attribs number|VBOAttributeDef[] When number, the maximum number of elements this VBO can have.
* Otherwise, an array of arrays specifying the layout.
- *
- * @return nil
* @see GL.OpenGL_Data_Types
* @see VBO:Upload
*/
@@ -1171,12 +1165,11 @@ size_t LuaVBOImpl::UploadImpl(const std::vector& dataVec, uint32_t elemOffs
/*** Binds engine side vertex or index VBO containing models (units, features) data.
- *
- * @function VBO:ModelsVBO
*
* Also fills in VBO definition data as they're set for engine models (no need to do VBO:Define()).
*
- * @return nil|number buffer size in bytes
+ * @function VBO:ModelsVBO
+ * @return number? buffer size in bytes
*/
size_t LuaVBOImpl::ModelsVBO()
{
@@ -1454,7 +1447,6 @@ int LuaVBOImpl::UnbindBufferRange(const GLuint index, const sol::optional e
/*** Logs the definition of the VBO to the console
*
* @function VBO:DumpDefinition
- * @return nil
*/
void LuaVBOImpl::DumpDefinition()
{
diff --git a/rts/Lua/LuaVFS.cpp b/rts/Lua/LuaVFS.cpp
index 5448a59b75..e4bdeb1ab3 100644
--- a/rts/Lua/LuaVFS.cpp
+++ b/rts/Lua/LuaVFS.cpp
@@ -817,11 +817,9 @@ int LuaVFS::UnmapArchive(lua_State* L)
* Compresses the specified folder.
* @function VFS.CompressFolder
* @param folderPath string
- * @param archiveType string? (Default: `"zip"`)The compression type (can
- * currently be only `"zip"`).
+ * @param archiveType string? (Default: `"zip"`) The compression type (can currently be only `"zip"`).
* @param compressedFilePath string? (Default: `folderPath .. ".sdz"`)
- * @param includeFolder boolean? (Default: `false`) Whether the archive should
- * have the specified folder as root.
+ * @param includeFolder boolean? (Default: `false`) Whether the archive should have the specified folder as root.
* @param mode string?
*/
int LuaVFS::CompressFolder(lua_State* L)
diff --git a/rts/Lua/library/Types.lua b/rts/Lua/library/Types.lua
index e7d8e0d5ee..942826e188 100644
--- a/rts/Lua/library/Types.lua
+++ b/rts/Lua/library/Types.lua
@@ -7,7 +7,7 @@
---Cartesian double (XY)
---
---@class xy
----@helper
+---@x_helper
---@field [1] number x
---@field [2] number y
@@ -16,7 +16,7 @@
---Cartesian triple (XYZ)
---
---@class xyz
----@helper
+---@x_helper
---@field [1] number x
---@field [2] number y
---@field [3] number z
@@ -26,7 +26,7 @@
---Cartesian quadruple (XYZW)
---
---@class xyzw
----@helper
+---@x_helper
---@field [1] number x
---@field [2] number y
---@field [3] number z
@@ -41,7 +41,7 @@
---Color triple (RGB)
---
---@class rgb
----@helper
+---@x_helper
---@field [1] number Red value.
---@field [2] number Green value.
---@field [3] number Blue value.
@@ -49,7 +49,7 @@
---Color quadruple (RGBA)
---
---@class rgba
----@helper
+---@x_helper
---@field [1] number Red value.
---@field [2] number Green value.
---@field [3] number Blue value.
@@ -58,7 +58,7 @@
---Indicator bytes representing color code operations during font rendering
---
---@class TextColorCode
----@helper
+---@x_helper
---@field Color string Indicates that the following bytes contain color code information
---@field ColorAndOutline string Indicates that the following bytes contain color code and outline information
---@field Reset string Indicates reset of the current color
@@ -90,7 +90,7 @@
---Highly dependent on the type of the current camera controller.
---
---@class CameraState
----@helper
+---@x_helper
---@field name CameraName The camera name.
---@field mode CameraMode The camera mode.
---@field fov number?