Documentation and API fixes (part of !2529)

apps/openmw_test_suite/lua/test_utilpackage.cpp

@@ -153,6 +153,8 @@ namespace
         lua.safe_script("moveAndScale = T.move(v(1, 2, 3)) * T.scale(0.5, 1, 0.5) * T.move(10, 20, 30)");
         EXPECT_EQ(getAsString(lua, "moveAndScale * v(0, 0, 0)"), "(6, 22, 18)");
         EXPECT_EQ(getAsString(lua, "moveAndScale * v(300, 200, 100)"), "(156, 222, 68)");
+        EXPECT_EQ(getAsString(lua, "moveAndScale:apply(v(0, 0, 0))"), "(6, 22, 18)");
+        EXPECT_EQ(getAsString(lua, "moveAndScale:apply(v(300, 200, 100))"), "(156, 222, 68)");
         EXPECT_THAT(getAsString(lua, "moveAndScale"),
             AllOf(StartsWith("TransformM{ move(6, 22, 18) scale(0.5, 1, 0.5) "), EndsWith(" }")));
         EXPECT_EQ(getAsString(lua, "T.identity"), "TransformM{ }");
@@ -162,6 +164,7 @@ namespace
         EXPECT_LT(get<float>(lua, "(rx * v(1, 2, 3) - v(1, -3, 2)):length()"), 1e-6);
         EXPECT_LT(get<float>(lua, "(ry * v(1, 2, 3) - v(3, 2, -1)):length()"), 1e-6);
         EXPECT_LT(get<float>(lua, "(rz * v(1, 2, 3) - v(-2, 1, 3)):length()"), 1e-6);
+        EXPECT_LT(get<float>(lua, "(rz:apply(v(1, 2, 3)) - v(-2, 1, 3)):length()"), 1e-6);
         lua.safe_script("rot = T.rotate(math.pi / 2, v(-1, -1, 0)) * T.rotateZ(math.pi / 4)");
         EXPECT_THAT(getAsString(lua, "rot"), HasSubstr("TransformQ"));
         EXPECT_LT(get<float>(lua, "(rot * v(1, 0, 0) - v(0, 0, 1)):length()"), 1e-6);

components/lua/utilpackage.cpp

@@ -185,6 +185,7 @@ namespace LuaUtil
             ss << "}";
             return ss.str();
         };
+        transMType["apply"] = [](const TransformM& a, const Vec3& b) { return a.mM.preMult(b); },
         transMType["inverse"] = [](const TransformM& m) {
             TransformM res;
             if (!res.mM.invert_4x3(m.mM))
@@ -209,6 +210,7 @@ namespace LuaUtil
                << axis.z() << ")) }";
             return ss.str();
         };
+        transQType["apply"] = [](const TransformQ& a, const Vec3& b) { return a.mQ * b; },
         transQType["inverse"] = [](const TransformQ& q) { return TransformQ{ q.mQ.inverse() }; };
 
         // Utility functions

files/data/scripts/omw/ai.lua

@@ -113,4 +113,3 @@ return {
         RemoveAIPackages = function(packageType) interfaces.AI.removePackages(packageType) end,
     },
 }
-

files/data/scripts/omw/mwui/init.lua

@@ -59,54 +59,85 @@ local templates = {}
 
 ---
 -- Container that adds padding around its content.
--- @field [parent=#MWUI] #table padding
+-- @field [parent=#Templates] openmw.ui#Template padding
 
 ---
 -- Standard spacing interval
--- @field [parent=#MWUI] #number interval
+-- @field [parent=#Templates] openmw.ui#Template interval
 require('scripts.omw.mwui.space')(templates)
 
 ---
--- Standard rectangular border
+-- Standard rectangular borders
--- @field [parent=#Templates] openmw.ui#Layout border
+-- @field [parent=#Templates] openmw.ui#Template borders
 
 ---
 -- Container wrapping the content with borders
--- @field [parent=#Templates] openmw.ui#Layout box
+-- @field [parent=#Templates] openmw.ui#Template box
 
 ---
 -- Same as box, but with a semi-transparent background
--- @field [parent=#Templates] openmw.ui#Layout boxTransparent
+-- @field [parent=#Templates] openmw.ui#Template boxTransparent
 ---
 -- Same as box, but with a solid background
--- @field [parent=#Templates] openmw.ui#Layout boxSolid
+-- @field [parent=#Templates] openmw.ui#Template boxSolid
+
+---
+-- Expanding vertical line
+-- @field [parent=#Templates] openmw.ui#Template verticalLine
+
+---
+-- Expanding horizontal line
+-- @field [parent=#Templates] openmw.ui#Template horizontalLine
+
+---
+-- Standard rectangular borders
+-- @field [parent=#Templates] openmw.ui#Template bordersThick
+
+---
+-- Container wrapping the content with borders
+-- @field [parent=#Templates] openmw.ui#Template boxThick
+
+---
+-- Same as box, but with a semi-transparent background
+-- @field [parent=#Templates] openmw.ui#Template boxTransparentThick
+---
+-- Same as box, but with a solid background
+-- @field [parent=#Templates] openmw.ui#Template boxSolidThick
+
+---
+-- Expanding vertical line
+-- @field [parent=#Templates] openmw.ui#Template verticalLineThick
+
+---
+-- Expanding horizontal line
+-- @field [parent=#Templates] openmw.ui#Template horizontalLineThick
 require('scripts.omw.mwui.borders')(templates)
 
 ---
 -- Standard "sand" colored text
--- @field [parent=#Templates] openmw.ui#Layout textNormal
+-- @field [parent=#Templates] openmw.ui#Template textNormal
 
 ---
 -- Header white colored text
--- @field [parent=#Templates] openmw.ui#Layout textHeader
+-- @field [parent=#Templates] openmw.ui#Template textHeader
 
 ---
 -- Standard "sand" colored multiline text
--- @field [parent=#Templates] openmw.ui#Layout textParagraph
+-- @field [parent=#Templates] openmw.ui#Template textParagraph
 require('scripts.omw.mwui.text')(templates)
 
 ---
 -- Single line text input
--- @field [parent=#Templates] openmw.ui#Layout textEditLine
+-- @field [parent=#Templates] openmw.ui#Template textEditLine
 
 ---
 -- Multiline text input
--- @field [parent=#Templates] openmw.ui#Layout textEditBox
+-- @field [parent=#Templates] openmw.ui#Template textEditBox
 require('scripts.omw.mwui.textEdit')(templates)
 
 ---
 -- Shades its children and makes them uninteractible
--- @field [parent=#Templates] openmw.ui#Layout disabled
+-- @field [parent=#Templates] openmw.ui#Template disabled
 require('scripts.omw.mwui.filters')(templates)
 
 ---

files/data/scripts/omw/settings/player.lua

@@ -20,9 +20,10 @@ require('scripts.omw.settings.renderers')(render.registerRenderer)
 -- @field #number order Groups within the same page are sorted by this number, or their key for equal values.
 --   Defaults to 0.
 -- @field #boolean permanentStorage Whether the group should be stored in permanent storage, or in the save file
--- @field #list<#SettingOptions> settings A [iterables#List](iterables.html#List) of #SettingOptions
+-- @field #list<#SettingOptions> settings A [iterables#List](iterables.html#List) table of #SettingOptions
 
 ---
+-- Table of setting options
 -- @type SettingOptions
 -- @field #string key A unique key
 -- @field #string name A key from the localization context

files/lua_api/global.doclua

@@ -24,11 +24,6 @@
 -- This is a global variable which hold the preloaded @{math} module.
 -- @field[parent = #global] math#math math preloaded module
 
-------------------------------------------------------------------------------
--- This library is an interface to the standard C math library.
--- This is a global variable which hold the preloaded @{omwutil} module.
--- @field[parent = #global] omwutil#omwutil ou preloaded module
-
 -------------------------------------------------------------------------------
 -- Issues an error when the value of its argument `v` is false (i.e.,
 -- **nil** or **false**); otherwise, returns all its arguments. `message` is an error

files/lua_api/openmw/camera.lua

@@ -4,14 +4,17 @@
 -- @module camera
 -- @usage local camera = require('openmw.camera')
 
+---
+-- Camera mode; see @{openmw.camera#MODE} for possible values
+-- @type Mode
 
 ---
 -- @type MODE Camera modes.
--- @field #number Static Camera doesn't track player; player inputs doesn't affect camera; use `setStaticPosition` to move the camera.
+-- @field #Mode Static Camera doesn't track player; player inputs doesn't affect camera; use `setStaticPosition` to move the camera.
--- @field #number FirstPerson First person mode.
+-- @field #Mode FirstPerson First person mode.
--- @field #number ThirdPerson Third person mode; player character turns to the view direction.
+-- @field #Mode ThirdPerson Third person mode; player character turns to the view direction.
--- @field #number Vanity Similar to Preview; camera slowly moves around the player.
+-- @field #Mode Vanity Similar to Preview; camera slowly moves around the player.
--- @field #number Preview Third person mode, but player character doesn't turn to the view direction.
+-- @field #Mode Preview Third person mode, but player character doesn't turn to the view direction.
 
 ---
 -- Camera modes.
@@ -20,17 +23,17 @@
 ---
 -- Return the current @{openmw.camera#MODE}.
 -- @function [parent=#camera] getMode
--- @return #MODE
+-- @return #Mode
 
 ---
 -- Return the mode the camera will switch to after the end of the current animation. Can be nil.
 -- @function [parent=#camera] getQueuedMode
--- @return #MODE
+-- @return #Mode
 
 ---
 -- Change @{openmw.camera#MODE}; if the second (optional, true by default) argument is set to false, the switching can be delayed (see `getQueuedMode`).
 -- @function [parent=#camera] setMode
--- @param #MODE mode
+-- @param #Mode mode
 -- @param #boolean force
 
 ---
@@ -223,4 +226,3 @@
 
 
 return nil
-

files/lua_api/openmw/core.lua

@@ -106,11 +106,12 @@
 -- Any object that exists in the game world and has a specific location.
 -- Player, actors, items, and statics are game objects.
 -- @type GameObject
+-- @extends #userdata
 -- @field #boolean enabled Whether the object is enabled or disabled. Global scripts can set the value. Items in containers or inventories can't be disabled.
 -- @field openmw.util#Vector3 position Object position.
 -- @field openmw.util#Vector3 rotation Object rotation (ZXY order).
 -- @field #Cell cell The cell where the object currently is. During loading a game and for objects in an inventory or a container `cell` is nil.
--- @field #table type Type of the object (one of the tables from the package @{openmw.types#types}).
+-- @field #any type Type of the object (one of the tables from the package @{openmw.types#types}).
 -- @field #number count Count (>1 means a stack of objects).
 -- @field #string recordId Returns record ID of the object in lowercase.
 
@@ -290,4 +291,3 @@
 
 
 return nil
-

files/lua_api/openmw/debug.lua

@@ -1,7 +1,7 @@
 ---
 -- `openmw.debug` is an interface to the engine debug utils.
 -- Can be used only by local scripts, that are attached to a player.
--- @module debug
+-- @module Debug
 -- @usage local debug = require('openmw.debug')
 
 
@@ -19,11 +19,11 @@
 
 ---
 -- Rendering mode values
--- @field [parent=#debug] #RENDER_MODE RENDER_MODE
+-- @field [parent=#Debug] #RENDER_MODE RENDER_MODE
 
 ---
 -- Toggles rendering mode
--- @function [parent=#debug] toggleRenderMode
+-- @function [parent=#Debug] toggleRenderMode
 -- @param #RENDER_MODE value
 
 ---
@@ -34,19 +34,19 @@
 
 ---
 -- Navigation mesh rendering mode values
--- @field [parent=#debug] #NAV_MESH_RENDER_MODE NAV_MESH_RENDER_MODE
+-- @field [parent=#Debug] #NAV_MESH_RENDER_MODE NAV_MESH_RENDER_MODE
 
 ---
 -- Sets navigation mesh rendering mode
--- @function [parent=#debug] setNavMeshRenderMode
+-- @function [parent=#Debug] setNavMeshRenderMode
 -- @param #NAV_MESH_RENDER_MODE value
 
 ---
 -- Enable/disable automatic reload of modified shaders
--- @function [parent=#debug] setShaderHotReloadEnabled
+-- @function [parent=#Debug] setShaderHotReloadEnabled
 -- @param #bool value
 
 ---
 -- To reload modified shaders
--- @function [parent=#debug] triggerShaderReload
+-- @function [parent=#Debug] triggerShaderReload
 return nil

files/lua_api/openmw/input.lua

@@ -20,7 +20,7 @@
 ---
 -- Is a keyboard button currently pressed.
 -- @function [parent=#input] isKeyPressed
--- @param #number keyCode Key code (see @{openmw.input#KEY})
+-- @param #KeyCode keyCode Key code (see @{openmw.input#KEY})
 -- @return #boolean
 
 ---
@@ -74,30 +74,34 @@
 ---
 -- Get state of a control switch. I.e. is player able to move/fight/jump/etc.
 -- @function [parent=#input] getControlSwitch
--- @param #string key Control type (see @{openmw.input#CONTROL_SWITCH})
+-- @param #ControlSwitch key Control type (see @{openmw.input#CONTROL_SWITCH})
 -- @return #boolean
 
 ---
 -- Set state of a control switch. I.e. forbid or allow player to move/fight/jump/etc.
 -- @function [parent=#input] setControlSwitch
--- @param #string key Control type (see @{openmw.input#CONTROL_SWITCH})
+-- @param #ControlSwitch key Control type (see @{openmw.input#CONTROL_SWITCH})
 -- @param #boolean value
 
 ---
 -- Returns a human readable name for the given key code
 -- @function [parent=#input] getKeyName
--- @param #number code A key code (see @{openmw.input#KEY})
+-- @param #KeyCode code A key code (see @{openmw.input#KEY})
 -- @return #string
 
+---
+-- String id of a @{#CONTROL_SWITCH}
+-- @type ControlSwitch
+
 ---
 -- @type CONTROL_SWITCH
--- @field [parent=#CONTROL_SWITCH] #string Controls Ability to move
+-- @field [parent=#CONTROL_SWITCH] #ControlSwitch Controls Ability to move
--- @field [parent=#CONTROL_SWITCH] #string Fighting Ability to attack
+-- @field [parent=#CONTROL_SWITCH] #ControlSwitch Fighting Ability to attack
--- @field [parent=#CONTROL_SWITCH] #string Jumping Ability to jump
+-- @field [parent=#CONTROL_SWITCH] #ControlSwitch Jumping Ability to jump
--- @field [parent=#CONTROL_SWITCH] #string Looking Ability to change view direction
+-- @field [parent=#CONTROL_SWITCH] #ControlSwitch Looking Ability to change view direction
--- @field [parent=#CONTROL_SWITCH] #string Magic Ability to use magic
+-- @field [parent=#CONTROL_SWITCH] #ControlSwitch Magic Ability to use magic
--- @field [parent=#CONTROL_SWITCH] #string ViewMode Ability to toggle 1st/3rd person view
+-- @field [parent=#CONTROL_SWITCH] #ControlSwitch ViewMode Ability to toggle 1st/3rd person view
--- @field [parent=#CONTROL_SWITCH] #string VanityMode Vanity view if player doesn't touch controls for a long time
+-- @field [parent=#CONTROL_SWITCH] #ControlSwitch VanityMode Vanity view if player doesn't touch controls for a long time
 
 ---
 -- Values that can be used with getControlSwitch/setControlSwitch.
@@ -192,110 +196,114 @@
 -- Values that can be used with getAxisValue.
 -- @field [parent=#input] #CONTROLLER_AXIS CONTROLLER_AXIS
 
+---
+-- Numeric id of a @{#KEY}
+-- @type KeyCode
+
 ---
 -- @type KEY
--- @field #number _0
+-- @field #KeyCode _0
--- @field #number _1
+-- @field #KeyCode _1
--- @field #number _2
+-- @field #KeyCode _2
--- @field #number _3
+-- @field #KeyCode _3
--- @field #number _4
+-- @field #KeyCode _4
--- @field #number _5
+-- @field #KeyCode _5
--- @field #number _6
+-- @field #KeyCode _6
--- @field #number _7
+-- @field #KeyCode _7
--- @field #number _8
+-- @field #KeyCode _8
--- @field #number _9
+-- @field #KeyCode _9
--- @field #number NP_0
+-- @field #KeyCode NP_0
--- @field #number NP_1
+-- @field #KeyCode NP_1
--- @field #number NP_2
+-- @field #KeyCode NP_2
--- @field #number NP_3
+-- @field #KeyCode NP_3
--- @field #number NP_4
+-- @field #KeyCode NP_4
--- @field #number NP_5
+-- @field #KeyCode NP_5
--- @field #number NP_6
+-- @field #KeyCode NP_6
--- @field #number NP_7
+-- @field #KeyCode NP_7
--- @field #number NP_8
+-- @field #KeyCode NP_8
--- @field #number NP_9
+-- @field #KeyCode NP_9
--- @field #number NP_Divide
+-- @field #KeyCode NP_Divide
--- @field #number NP_Enter
+-- @field #KeyCode NP_Enter
--- @field #number NP_Minus
+-- @field #KeyCode NP_Minus
--- @field #number NP_Multiply
+-- @field #KeyCode NP_Multiply
--- @field #number NP_Delete
+-- @field #KeyCode NP_Delete
--- @field #number NP_Plus
+-- @field #KeyCode NP_Plus
--- @field #number F1
+-- @field #KeyCode F1
--- @field #number F2
+-- @field #KeyCode F2
--- @field #number F3
+-- @field #KeyCode F3
--- @field #number F4
+-- @field #KeyCode F4
--- @field #number F5
+-- @field #KeyCode F5
--- @field #number F6
+-- @field #KeyCode F6
--- @field #number F7
+-- @field #KeyCode F7
--- @field #number F8
+-- @field #KeyCode F8
--- @field #number F9
+-- @field #KeyCode F9
--- @field #number F10
+-- @field #KeyCode F10
--- @field #number F11
+-- @field #KeyCode F11
--- @field #number F12
+-- @field #KeyCode F12
--- @field #number A
+-- @field #KeyCode A
--- @field #number B
+-- @field #KeyCode B
--- @field #number C
+-- @field #KeyCode C
--- @field #number D
+-- @field #KeyCode D
--- @field #number E
+-- @field #KeyCode E
--- @field #number F
+-- @field #KeyCode F
--- @field #number G
+-- @field #KeyCode G
--- @field #number H
+-- @field #KeyCode H
--- @field #number I
+-- @field #KeyCode I
--- @field #number J
+-- @field #KeyCode J
--- @field #number K
+-- @field #KeyCode K
--- @field #number L
+-- @field #KeyCode L
--- @field #number M
+-- @field #KeyCode M
--- @field #number N
+-- @field #KeyCode N
--- @field #number O
+-- @field #KeyCode O
--- @field #number P
+-- @field #KeyCode P
--- @field #number Q
+-- @field #KeyCode Q
--- @field #number R
+-- @field #KeyCode R
--- @field #number S
+-- @field #KeyCode S
--- @field #number T
+-- @field #KeyCode T
--- @field #number U
+-- @field #KeyCode U
--- @field #number V
+-- @field #KeyCode V
--- @field #number W
+-- @field #KeyCode W
--- @field #number X
+-- @field #KeyCode X
--- @field #number Y
+-- @field #KeyCode Y
--- @field #number Z
+-- @field #KeyCode Z
--- @field #number LeftArrow
+-- @field #KeyCode LeftArrow
--- @field #number RightArrow
+-- @field #KeyCode RightArrow
--- @field #number UpArrow
+-- @field #KeyCode UpArrow
--- @field #number DownArrow
+-- @field #KeyCode DownArrow
--- @field #number LeftAlt
+-- @field #KeyCode LeftAlt
--- @field #number LeftCtrl
+-- @field #KeyCode LeftCtrl
--- @field #number LeftBracket
+-- @field #KeyCode LeftBracket
--- @field #number LeftSuper
+-- @field #KeyCode LeftSuper
--- @field #number LeftShift
+-- @field #KeyCode LeftShift
--- @field #number RightAlt
+-- @field #KeyCode RightAlt
--- @field #number RightCtrl
+-- @field #KeyCode RightCtrl
--- @field #number RightBracket
+-- @field #KeyCode RightBracket
--- @field #number RightSuper
+-- @field #KeyCode RightSuper
--- @field #number RightShift
+-- @field #KeyCode RightShift
--- @field #number Apostrophe
+-- @field #KeyCode Apostrophe
--- @field #number BackSlash
+-- @field #KeyCode BackSlash
--- @field #number Backspace
+-- @field #KeyCode Backspace
--- @field #number CapsLock
+-- @field #KeyCode CapsLock
--- @field #number Comma
+-- @field #KeyCode Comma
--- @field #number Delete
+-- @field #KeyCode Delete
--- @field #number End
+-- @field #KeyCode End
--- @field #number Enter
+-- @field #KeyCode Enter
--- @field #number Equals
+-- @field #KeyCode Equals
--- @field #number Escape
+-- @field #KeyCode Escape
--- @field #number Home
+-- @field #KeyCode Home
--- @field #number Insert
+-- @field #KeyCode Insert
--- @field #number Minus
+-- @field #KeyCode Minus
--- @field #number NumLock
+-- @field #KeyCode NumLock
--- @field #number PageDown
+-- @field #KeyCode PageDown
--- @field #number PageUp
+-- @field #KeyCode PageUp
--- @field #number Pause
+-- @field #KeyCode Pause
--- @field #number Period
+-- @field #KeyCode Period
--- @field #number PrintScreen
+-- @field #KeyCode PrintScreen
--- @field #number ScrollLock
+-- @field #KeyCode ScrollLock
--- @field #number Semicolon
+-- @field #KeyCode Semicolon
--- @field #number Slash
+-- @field #KeyCode Slash
--- @field #number Space
+-- @field #KeyCode Space
--- @field #number Tab
+-- @field #KeyCode Tab
 
 ---
 -- Key codes.
@@ -305,7 +313,7 @@
 -- The argument of `onKeyPress`/`onKeyRelease` engine handlers.
 -- @type KeyboardEvent
 -- @field [parent=#KeyboardEvent] #string symbol The pressed symbol (1-symbol string if can be represented or an empty string otherwise).
--- @field [parent=#KeyboardEvent] #string code Key code.
+-- @field [parent=#KeyboardEvent] #KeyCode code Key code.
 -- @field [parent=#KeyboardEvent] #boolean withShift Is `Shift` key pressed.
 -- @field [parent=#KeyboardEvent] #boolean withCtrl Is `Control` key pressed.
 -- @field [parent=#KeyboardEvent] #boolean withAlt Is `Alt` key pressed.
@@ -320,4 +328,3 @@
 -- @field [parent=#TouchEvent] #number pressure Pressure of the finger.
 
 return nil
-

files/lua_api/openmw/interfaces.lua

@@ -0,0 +1,23 @@
+---
+-- @module interfaces
+-- @usage local I = require('openmw.interfaces')
+
+---
+-- @field [parent=#interfaces] scripts.omw.camera.camera#scripts.omw.camera.camera Camera
+
+---
+-- @field [parent=#interfaces] scripts.omw.settings.player#scripts.omw.settings.player Settings
+
+---
+-- @field [parent=#interfaces] scripts.omw.mwui.init#scripts.omw.mwui.init MWUI
+
+---
+-- @field [parent=#interfaces] scripts.omw.ai#scripts.omw.ai AI
+
+---
+-- @function [parent=#interfaces] __index
+-- @param #interfaces self
+-- @param #string key
+-- @return #any
+
+return nil

files/lua_api/openmw/nearby.lua

@@ -41,7 +41,7 @@
 
 ---
 -- Collision types that are used in `castRay`.
--- Several types can be combined with '+'.
+-- Several types can be combined with @{openmw_util#util.bitOr}.
 -- @field [parent=#nearby] #COLLISION_TYPE COLLISION_TYPE
 
 ---
@@ -52,16 +52,20 @@
 -- @field [parent=#RayCastingResult] openmw.util#Vector3 hitNormal Normal to the surface in the collision point (nil if no collision)
 -- @field [parent=#RayCastingResult] openmw.core#GameObject hitObject The object the ray has collided with (can be nil)
 
+---
+-- A table of parameters for @{#nearby.castRay}
+-- @type CastRayOptions
+-- @field openmw.core#GameObject ignore An object to ignore (specify here the source of the ray)
+-- @field #number collisionType Object types to work with (see @{openmw.nearby#COLLISION_TYPE})
+-- @field #number radius The radius of the ray (zero by default). If not zero then castRay actually casts a sphere with given radius.
+--  NOTE: currently `ignore` is not supported if `radius>0`.
+
 ---
 -- Cast ray from one point to another and return the first collision.
 -- @function [parent=#nearby] castRay
 -- @param openmw.util#Vector3 from Start point of the ray.
 -- @param openmw.util#Vector3 to End point of the ray.
--- @param #table options An optional table with additional optional arguments. Can contain:  
+-- @param #CastRayOptions options An optional table with additional optional arguments
--- `ignore` - an object to ignore (specify here the source of the ray);  
--- `collisionType` - object types to work with (see @{openmw.nearby#COLLISION_TYPE}), several types can be combined with '+';  
--- `radius` - the radius of the ray (zero by default). If not zero then castRay actually casts a sphere with given radius.  
--- NOTE: currently `ignore` is not supported if `radius>0`.
 -- @return #RayCastingResult
 -- @usage if nearby.castRay(pointA, pointB).hit then print('obstacle between A and B') end
 -- @usage local res = nearby.castRay(self.position, enemy.position, {ignore=self})
@@ -150,7 +154,8 @@
 --       (default: 1);
 --   * `destinationTolerance` - a floating point number representing maximum allowed distance between destination and a
 --     nearest point on the navigation mesh in addition to agent size (default: 1);
--- @return @{#FIND_PATH_STATUS}, a collection of @{openmw.util#Vector3}
+-- @return #FIND_PATH_STATUS
+-- @return #list<openmw.util#Vector3>
 -- @usage local status, path = nearby.findPath(source, destination)
 -- @usage local status, path = nearby.findPath(source, destination, {
 --     includeFlags = nearby.NAVIGATOR_FLAGS.Walk + nearby.NAVIGATOR_FLAGS.OpenDoor,
@@ -177,7 +182,7 @@
 --   * `includeFlags` - allowed areas for agent to move, a sum of @{#NAVIGATOR_FLAGS} values
 --     (default: @{#NAVIGATOR_FLAGS.Walk} + @{#NAVIGATOR_FLAGS.Swim} +
 --     @{#NAVIGATOR_FLAGS.OpenDoor} + @{#NAVIGATOR_FLAGS.UsePathgrid});
--- @return @{openmw.util#Vector3} or nil
+-- @return openmw.util#Vector3, #nil
 -- @usage local position = nearby.findRandomPointAroundCircle(position, maxRadius)
 -- @usage local position = nearby.findRandomPointAroundCircle(position, maxRadius, {
 --     includeFlags = nearby.NAVIGATOR_FLAGS.Walk,
@@ -201,7 +206,7 @@
 --   * `includeFlags` - allowed areas for agent to move, a sum of @{#NAVIGATOR_FLAGS} values
 --     (default: @{#NAVIGATOR_FLAGS.Walk} + @{#NAVIGATOR_FLAGS.Swim} +
 --     @{#NAVIGATOR_FLAGS.OpenDoor} + @{#NAVIGATOR_FLAGS.UsePathgrid});
--- @return @{openmw.util#Vector3} or nil
+-- @return openmw.util#Vector3, #nil
 -- @usage local position = nearby.castNavigationRay(from, to)
 -- @usage local position = nearby.castNavigationRay(from, to, {
 --     includeFlags = nearby.NAVIGATOR_FLAGS.Swim,

files/lua_api/openmw/storage.lua

@@ -50,12 +50,14 @@
 -- @function [parent=#StorageSection] get
 -- @param self
 -- @param #string key
+-- @return #any
 
 ---
 -- Get value by a string key; if value is a table returns a copy.
 -- @function [parent=#StorageSection] getCopy
 -- @param self
 -- @param #string key
+-- @return #any
 
 ---
 -- Subscribe to changes in this section.
@@ -95,4 +97,3 @@
 -- @param #any value
 
 return nil
-

files/lua_api/openmw/types.lua

@@ -119,16 +119,22 @@
 -- @param openmw.core#GameObject item
 -- @return #boolean
 
+---
+-- Map from values of @{#EQUIPMENT_SLOT} to items @{openmw.core#GameObject}s
+-- @type EquipmentTable
+-- @map <#number, openmw.core#GameObject>
+
 ---
 -- Get equipment.
 -- Has two overloads:
--- 1) With single argument: returns a table `slot` -> @{openmw.core#GameObject} of currently equipped items.
+-- 1) With a single argument: returns a table `slot` -> @{openmw.core#GameObject} of currently equipped items.
 -- See @{#EQUIPMENT_SLOT}. Returns empty table if the actor doesn't have
 -- equipment slots.
 -- 2) With two arguments: returns an item equipped to the given slot.
 -- @function [parent=#Actor] equipment
 -- @param openmw.core#GameObject actor
--- @param #number slot (optional argument)
+-- @param #number slot Optional number of the equipment slot
+-- @return #EquipmentTable, openmw.core#GameObject
 
 ---
 -- Set equipment.
@@ -138,7 +144,7 @@
 -- used only in local scripts and only on self.
 -- @function [parent=#Actor] setEquipment
 -- @param openmw.core#GameObject actor
--- @param equipment
+-- @param #EquipmentTable equipment
 -- @usage local self = require('openmw.self')
 -- local Actor = require('openmw.types').Actor
 -- Actor.setEquipment(self, {}) -- unequip all
@@ -1143,4 +1149,3 @@
 -- @field #string model VFS path to the model
 
 return nil
-

files/lua_api/openmw/ui.lua

@@ -31,6 +31,9 @@
 -- @field Text Display text
 -- @field TextEdit Accepts user text input
 -- @field Window Can be moved and resized by the user
+-- @field Image Displays an image
+-- @field Flex Aligns widgets in a row or column
+-- @field Container Automatically wraps around its contents
 
 ---
 -- Shows given message at the bottom of the screen.
@@ -104,15 +107,28 @@
 ---
 -- Layout
 -- @type Layout
+-- @field type Type of the widget, one of the values in #TYPE. Must match the type in #Template if both are present
+-- @field #string layer Optional layout to display in. Only applies for the root widget.
+--   Note: if the #Element isn't attached to anything, it won't be visible!
 -- @field #string name Optional name of the layout. Allows access by name from Content
 -- @field #table props Optional table of widget properties
 -- @field #table events Optional table of event callbacks
 -- @field #Content content Optional @{openmw.ui#Content} of children layouts
+-- @field #Template template Optional #Template
+-- @field #table external Optional table of external properties
+-- @field userData Arbitrary data for you to use, e. g. when receiving the layout in an event callback
+
+---
+-- Template
+-- @type Template
+-- @field #table props
+-- @field #Content content
+-- @field type One of the values in #TYPE, serves as the default value for the #Layout
 
 ---
 -- @type Layer
 -- @field #string name Name of the layer
--- @field openmw.util#vector2 size Size of the layer in pixels
+-- @field openmw.util#Vector2 size Size of the layer in pixels
 
 ---
 -- Layers. Implements [iterables#List](iterables.html#List) of #Layer.
@@ -173,6 +189,13 @@
 --    print('widget',content[i].name,'at',i)
 -- end
 
+---
+-- Content also acts as a map of names to Layouts
+-- @function [parent=#Content] __index
+-- @param self
+-- @param #string name
+-- @return #Layout
+
 ---
 -- Puts the layout at given index by shifting all the elements after it
 -- @function [parent=#Content] insert
@@ -222,8 +245,9 @@
 
 ---
 -- Register a new texture resource. Can be used to manually atlas UI textures.
--- @function [parent=#ui] texture #TextureResource
+-- @function [parent=#ui] texture
 -- @param #TextureResourceOptions options
+-- @return #TextureResource
 -- @usage
 -- local ui = require('openmw.ui')
 -- local vector2 = require('openmw.util').vector2

files/lua_api/openmw/util.lua

@@ -116,6 +116,30 @@
 -- @param #number y.
 -- @return #Vector2.
 
+---
+-- @function [parent=#Vector2] __add
+-- @param self
+-- @param #Vector2 v
+-- @return #Vector2 sum of the vectors
+
+---
+-- @function [parent=#Vector2] __sub
+-- @param self
+-- @param #Vector2 v
+-- @return #Vector2 difference of the vectors
+
+---
+-- @function [parent=#Vector2] __mul
+-- @param self
+-- @param #number k
+-- @return #Vector2 vector multiplied by a number
+
+---
+-- @function [parent=#Vector2] __div
+-- @param self
+-- @param #number k
+-- @return #Vector2 vector divided by a number
+
 ---
 -- Length of the vector.
 -- @function [parent=#Vector2] length
@@ -130,11 +154,11 @@
 
 ---
 -- Normalizes vector.
--- Returns two values: normalized vector and the length of the original vector.
 -- It doesn't change the original vector.
 -- @function [parent=#Vector2] normalize
 -- @param self
--- @return #Vector2, #number
+-- @return #Vector2 normalized vector
+-- @return #number the length of the original vector
 
 ---
 -- Rotates 2D vector clockwise.
@@ -195,6 +219,35 @@
 -- @param #number z.
 -- @return #Vector3.
 
+---
+-- @function [parent=#Vector3] __add
+-- @param self
+-- @param #Vector3 v
+-- @return #Vector3 sum of the vectors
+
+---
+-- @function [parent=#Vector3] __sub
+-- @param self
+-- @param #Vector3 v
+-- @return #Vector3 difference of the vectors
+
+---
+-- @function [parent=#Vector3] __mul
+-- @param self
+-- @param #number k
+-- @return #Vector3 vector multiplied by a number
+
+---
+-- @function [parent=#Vector3] __div
+-- @param self
+-- @param #number k
+-- @return #Vector3 vector divided by a number
+
+---
+-- @function [parent=#Vector3] __tostring
+-- @param self
+-- @return #string
+
 ---
 -- Length of the vector
 -- @function [parent=#Vector3] length
@@ -209,11 +262,11 @@
 
 ---
 -- Normalizes vector.
--- Returns two values: normalized vector and the length of the original vector.
 -- It doesn't change the original vector.
 -- @function [parent=#Vector3] normalize
 -- @param self
--- @return #Vector3, #number
+-- @return #Vector3 normalized vector
+-- @return #number the length of the original vector
 
 ---
 -- Dot product.
@@ -274,6 +327,35 @@
 -- @param #number w.
 -- @return #Vector4.
 
+---
+-- @function [parent=#Vector4] __add
+-- @param self
+-- @param #Vector4 v
+-- @return #Vector4 sum of the vectors
+
+---
+-- @function [parent=#Vector4] __sub
+-- @param self
+-- @param #Vector4 v
+-- @return #Vector4 difference of the vectors
+
+---
+-- @function [parent=#Vector4] __mul
+-- @param self
+-- @param #number k
+-- @return #Vector4 vector multiplied by a number
+
+---
+-- @function [parent=#Vector4] __div
+-- @param self
+-- @param #number k
+-- @return #Vector4 vector divided by a number
+
+---
+-- @function [parent=#Vector4] __tostring
+-- @param self
+-- @return #string
+
 ---
 -- Length of the vector
 -- @function [parent=#Vector4] length
@@ -288,11 +370,11 @@
 
 ---
 -- Normalizes vector.
--- Returns two values: normalized vector and the length of the original vector.
 -- It doesn't change the original vector.
 -- @function [parent=#Vector4] normalize
 -- @param self
--- @return #Vector4, #number
+-- @return #Vector4 normalized vector
+-- @return #number the length of the original vector
 
 ---
 -- Dot product.
@@ -376,11 +458,25 @@
 ---
 -- @type Transform
 
+---
+-- Combine transforms (will apply in reverse order)
+-- @function [parent=#Transform] __mul
+-- @param self
+-- @param #Transform t
+-- @return #Transform
+
 ---
 -- Returns the inverse transform.
 -- @function [parent=#Transform] inverse
 -- @param self
--- @return #Transform.
+-- @return #Transform
+
+---
+-- Apply transform to a vector
+-- @function [parent=#Transform] apply
+-- @param self
+-- @param #Vector3 v
+-- @return #Vector3
 
 ---
 -- @type TRANSFORM
@@ -389,8 +485,8 @@
 ---
 -- Movement by given vector.
 -- @function [parent=#TRANSFORM] move
--- @param #Vector3 offset.
+-- @param #Vector3 offset
--- @return #Transform.
+-- @return #Transform
 -- @usage
 -- -- Accepts either 3 numbers or a 3D vector
 -- util.transform.move(x, y, z)
@@ -453,4 +549,3 @@
 -- local deltaAngle = math.atan2(relativeTargetPos.y, relativeTargetPos.x)
 
 return nil
-