Lua docs: minor grammar fixes (mostly missing articles)

files/data/openmw_aux/time.lua

@@ -51,7 +51,7 @@ end
 
 ---
 -- Run given function repeatedly.
--- Note that loading a save stops the evaluation. If it should work always, call it during initialization of the script (i.e. not in a handler)
+-- Note that loading a save stops the evaluation. If it should always work, call it during the initialization of the script (i.e. not in a handler)
 -- @function [parent=#time] runRepeatedly
 -- @param #function fn the function that should be called
 -- @param #number period interval

files/data/openmw_aux/util.lua

@@ -23,21 +23,21 @@ local function deepToString(val, level, prefix)
 end
 
 ---
--- Works like `tostring` but shows also content of tables.
+-- Works like `tostring` but also shows the content of tables.
 -- @function [parent=#util] deepToString
--- @param #any value The value to convert to string
+-- @param #any value The value to convert to a string
--- @param #number maxDepth Max depth of tables unpacking (optional, 1 by default)
+-- @param #number maxDepth Max depth of table unpacking (optional, 1 by default)
 function aux_util.deepToString(value, maxDepth)
     return deepToString(value, maxDepth, '')
 end
 
 ---
--- Finds the element the minimizes `scoreFn`.
+-- Finds the element in the array given the lowest score by `scoreFn`.
 -- @function [parent=#util] findMinScore
 -- @param #table array Any array
 -- @param #function scoreFn Function that returns either nil/false or a number for each element of the array
--- @return element The element the minimizes `scoreFn`
+-- @return element The element given the lowest score
--- @return #number score The output of `scoreFn(element)`
+-- @return #number score The score given to the chosen element by `scoreFn`
 -- @return #number index The index of the chosen element in the array
 -- @usage -- Find the nearest NPC
 -- local nearestNPC, distToNPC = aux_util.findMinScore(

files/data/scripts/omw/activationhandlers.lua

@@ -58,7 +58,7 @@ return {
         -- @field [parent=#Activation] #number version
         version = 0,
 
-        --- Add new activation handler for a specific object.
+        --- Add a new activation handler for a specific object.
         -- If `handler(object, actor)` returns false, other handlers for
         -- the same object (including type handlers) will be skipped.
         -- @function [parent=#Activation] addHandlerForObject
@@ -73,7 +73,7 @@ return {
             handlers[#handlers + 1] = handler
         end,
 
-        --- Add new activation handler for a type of objects.
+        --- Add a new activation handler for a type of object.
         -- If `handler(object, actor)` returns false, other handlers for
         -- the same object (including type handlers) will be skipped.
         -- @function [parent=#Activation] addHandlerForType

files/data/scripts/omw/ai.lua

@@ -86,7 +86,7 @@ return {
         -- @return #boolean
         isFleeing = function() return self:_isFleeing() end,
 
-        --- Start new AI package.
+        --- Start a new AI package.
         -- @function [parent=#AI] startPackage
         -- @param #table options See the "AI packages" page.
         startPackage = startPackage,
@@ -128,7 +128,7 @@ return {
             end
         end,
 
-        --- Get list of targets of all packages of the given type.
+        --- Get a list of targets from all packages of the given type.
         -- @function [parent=#AI] getTargets
         -- @param #string packageType
         -- @return #list<openmw.core#GameObject>

files/data/scripts/omw/camera/camera.lua

@@ -250,16 +250,16 @@ return {
         -- @field [parent=#Camera] #number version
         version = 1,
 
-        --- Return primary mode (MODE.FirstPerson or MODE.ThirdPerson).
+        --- Return the primary mode (MODE.FirstPerson or MODE.ThirdPerson).
         -- @function [parent=#Camera] getPrimaryMode
         -- @return #number @{openmw.camera#MODE}
         getPrimaryMode = function() return primaryMode end,
 
-        --- Get base third person distance (without applying angle and speed modifiers).
+        --- Get the base third person distance (without applying angle and speed modifiers).
         -- @function [parent=#Camera] getBaseThirdPersonDistance
         -- @return #number
         getBaseThirdPersonDistance = function() return third_person.baseDistance end,
-        --- Set base third person distance
+        --- Set the base third person distance
         -- @function [parent=#Camera] setBaseThirdPersonDistance
         -- @param #number value
         setBaseThirdPersonDistance = function(v) third_person.baseDistance = v end,

files/data/scripts/omw/combat/local.lua

@@ -299,7 +299,7 @@ end
 
 ---
 -- @type AttackInfo
--- @field [parent=#AttackInfo] #table damage A table mapping stat name (health, fatigue, or magicka) to number. For example, {health = 50, fatigue = 10} will cause 50 damage to health and 10 to fatigue (before adjusting for armor and difficulty). This field is ignored for failed attacks.
+-- @field [parent=#AttackInfo] #table damage A table mapping a stat name (health, fatigue, or magicka) to a number. For example, {health = 50, fatigue = 10} will cause 50 damage to health and 10 to fatigue (before adjusting for armor and difficulty). This field is ignored for failed attacks.
 -- @field [parent=#AttackInfo] #number strength A number between 0 and 1 representing the attack strength. This field is ignored for failed attacks.
 -- @field [parent=#AttackInfo] #boolean successful Whether the attack was successful or not.
 -- @field [parent=#AttackInfo] #AttackSourceType sourceType What class of attack this is.
@@ -333,7 +333,7 @@ return {
 
         --- Add new onHit handler for this actor
         -- If `handler(attack)` returns false, other handlers for
-        -- the call will be skipped. where attack is the same @{#AttackInfo} passed to #Combat.onHit
+        -- the call will be skipped. Where attack is the same @{#AttackInfo} passed to #Combat.onHit
         -- @function [parent=#Combat] addOnHitHandler
         -- @param #function handler The handler.
         addOnHitHandler = function(handler)
@@ -349,7 +349,7 @@ return {
         -- @return #number Damage adjusted for armor
         adjustDamageForArmor = function(damage, actor) return adjustDamageForArmor(damage, actor or self) end,
 
-        --- Calculates a difficulty multiplier based on current difficulty settings
+        --- Calculates a difficulty multiplier based on the current difficulty settings
         -- and adjusts damage accordingly. Has no effect if both this actor and the
         -- attacker are NPCs, or if both are Players.
         -- @function [parent=#Combat] adjustDamageForDifficulty

files/data/scripts/omw/crimes.lua

@@ -7,7 +7,7 @@ local I = require('openmw.interfaces')
 -- @field openmw.core#GameObject victim The victim of the crime (optional)
 -- @field openmw.types#OFFENSE_TYPE_IDS type The type of the crime to commit. See @{openmw.types#OFFENSE_TYPE_IDS} (required)
 -- @field #string faction ID of the faction the crime is committed against (optional)
--- @field #number arg The amount to increase the player bounty by, if the crime type is theft. Ignored otherwise (optional, defaults to 0)
+-- @field #number arg The amount to increase the player bounty by if the crime type is theft. Ignored otherwise (optional, defaults to 0)
 -- @field #boolean victimAware Whether the victim is aware of the crime (optional, defaults to false)
 
 ---

files/data/scripts/omw/mechanics/animationcontroller.lua

@@ -100,7 +100,7 @@ return {
         -- @param #table options The table of play options that will be passed to @{openmw.animation#playBlended}
         playBlendedAnimation = playBlendedAnimation,
 
-        --- Add new playBlendedAnimation handler for this actor
+        --- Add a new playBlendedAnimation handler for this actor
         -- If `handler(groupname, options)` returns false, other handlers for
         -- the call will be skipped.
         -- @function [parent=#AnimationController] addPlayBlendedAnimationHandler
@@ -109,13 +109,13 @@ return {
             playBlendedHandlers[#playBlendedHandlers + 1] = handler
         end,
 
-        --- Add new text key handler for this actor
+        --- Add a new text key handler for this actor
         -- While playing, some animations emit text key events. Register a handle to listen for all
         -- text key events associated with this actor's animations.
         -- If `handler(groupname, key)` returns false, other handlers for
         -- the call will be skipped.
         -- @function [parent=#AnimationController] addTextKeyHandler
-        -- @param #string groupname Name of the animation group to listen to keys for. If the empty string or nil, all keys will be received
+        -- @param #string groupname Name of the animation group to listen to keys for. If it is an empty string or nil, all keys will be received
         -- @param #function handler The handler.
         addTextKeyHandler = function(groupname, handler)
             if not groupname then

files/data/scripts/omw/skillhandlers.lua

@@ -7,7 +7,7 @@ local NPC = require('openmw.types').NPC
 local Skill = core.stats.Skill
 
 ---
--- Table of skill use types defined by morrowind.
+-- Table of skill use types defined by Morrowind.
 -- Each entry corresponds to an index into the available skill gain values
 -- of a @{openmw.core#SkillRecord}
 -- @type SkillUseType
@@ -188,7 +188,7 @@ return {
         -- If `handler(skillid, source, options)` returns false, other handlers (including the default skill level up handler) 
         -- will be skipped. Where skillid and source are the parameters passed to @{#SkillProgression.skillLevelUp}, and options is
         -- a modifiable table of skill level up values, and can be modified to change the behavior of later handlers. 
-        -- These values are calculated based on vanilla mechanics. Setting any value to nil will cause that mechanic to be skipped. By default contains these values:
+        -- These values are calculated based on vanilla mechanics. Setting any value to nil will cause that mechanic to be skipped. By default it contains these values:
         --
         --   * `skillIncreaseValue` - The numeric amount of skill levels gained. By default this is 1, except when the source is jail in which case it will instead be -1 for all skills except sneak and security.
         --   * `levelUpProgress` - The numeric amount of level up progress gained.
@@ -216,7 +216,7 @@ return {
         
         --- Trigger a skill use, activating relevant handlers
         -- @function [parent=#SkillProgression] skillUsed
-        -- @param #string skillid The if of the skill that was used
+        -- @param #string skillid The ID of the skill that was used
         -- @param options A table of parameters. Must contain one of `skillGain` or `useType`. It's best to always include `useType` if applicable, even if you set `skillGain`, as it may be used
         -- by handlers to make decisions. See the addSkillUsedHandler example at the top of this page.
         --

files/data/scripts/omw/usehandlers.lua

@@ -58,7 +58,7 @@ return {
             handlers[#handlers + 1] = handler
         end,
 
-        --- Add new use action handler for a type of objects.
+        --- Add new use action handler for a type of object.
         -- If `handler(object, actor, options)` returns false, other handlers for
         -- the same object (including type handlers) will be skipped.
         -- @function [parent=#ItemUsage] addHandlerForType

files/lua_api/openmw/camera.lua

@@ -37,12 +37,12 @@
 -- @param #boolean force
 
 ---
--- If set to true then after switching from Preview to ThirdPerson the player character turns to the camera view direction. Otherwise the camera turns to the character view direction.
+-- If set to true then after switching from Preview to ThirdPerson the player character turns to the camera view direction. Otherwise, the camera turns to the character view direction.
 -- @function [parent=#camera] allowCharacterDeferredRotation
 -- @param #boolean boolValue
 
 ---
--- Show/hide crosshair.
+-- Show/hide the crosshair.
 -- @function [parent=#camera] showCrosshair
 -- @param #boolean boolValue
 
@@ -79,12 +79,12 @@
 -- @param #number value
 
 ---
--- Get camera roll angle (radians).
+-- Get the camera roll angle (radians).
 -- @function [parent=#camera] getRoll
 -- @return #number
 
 ---
--- Set camera roll angle (radians).
+-- Set the camera roll angle (radians).
 -- @function [parent=#camera] setRoll
 -- @param #number value
 
@@ -126,7 +126,7 @@
 -- @param #number value
 
 ---
--- Set camera position; can be used only if camera is in Static mode.
+-- Set the camera position; can be used only if camera is in Static mode.
 -- @function [parent=#camera] setStaticPosition
 -- @param openmw.util#Vector3 pos
 
@@ -141,16 +141,16 @@
 -- @param openmw.util#Vector3 offset
 
 ---
--- Preferred offset between tracked position (see `getTrackedPosition`) and the camera focal point (the center of the screen) in third person mode.
+-- Preferred offset between the tracked position (see `getTrackedPosition`) and the camera focal point (the center of the screen) in third person mode.
 -- See `setFocalPreferredOffset`.
 -- @function [parent=#camera] getFocalPreferredOffset
 -- @return openmw.util#Vector2
 
 ---
--- Set preferred offset between tracked position (see `getTrackedPosition`) and the camera focal point (the center of the screen) in third person mode.
+-- Set the preferred offset between the tracked position (see `getTrackedPosition`) and the camera focal point (the center of the screen) in third person mode.
 -- The offset is a 2d vector (X, Y) where X is horizontal (to the right from the character) and Y component is vertical (upward).
 -- The real offset can differ from the preferred one during smooth transition or if blocked by an obstacle.
--- Smooth transition happens by default every time when the preferred offset was changed. Use `instantTransition()` to skip the current transition.
+-- Smooth transition happens by default every time the preferred offset changes. Use `instantTransition()` to skip the current transition.
 -- @function [parent=#camera] setFocalPreferredOffset
 -- @param openmw.util#Vector2 offset
 
@@ -171,7 +171,7 @@
 
 ---
 -- Set the speed coefficient of focal point (the center of the screen in third person mode) smooth transition.
--- Smooth transition happens by default every time when the preferred offset was changed. Use `instantTransition()` to skip the current transition.
+-- Smooth transition happens by default every time the preferred offset changes. Use `instantTransition()` to skip the current transition.
 -- @function [parent=#camera] setFocalTransitionSpeed
 -- Set the speed coefficient
 -- @param #number speed
@@ -180,50 +180,50 @@
 -- Make instant the current transition of camera focal point and the current deferred rotation (see `allowCharacterDeferredRotation`).
 -- @function [parent=#camera] instantTransition
 
---- Get current camera collision type (see @{openmw.nearby#COLLISION_TYPE}).
+--- Get the current camera collision type (see @{openmw.nearby#COLLISION_TYPE}).
 -- @function [parent=#camera] getCollisionType
 -- @return #number
 
---- Set camera collision type (see @{openmw.nearby#COLLISION_TYPE}).
+--- Set the camera collision type (see @{openmw.nearby#COLLISION_TYPE}).
 -- @function [parent=#camera] setCollisionType
 -- @param #number collisionType
 
---- Return base field of view vertical angle in radians
+--- Return the base field of view vertical angle in radians
 -- @function [parent=#camera] getBaseFieldOfView
 -- @return #number
 
---- Return current field of view vertical angle in radians
+--- Return the current field of view vertical angle in radians
 -- @function [parent=#camera] getFieldOfView
 -- @return #number
 
---- Set field of view
+--- Set the field of view
 -- @function [parent=#camera] setFieldOfView
 -- @param #number fov Field of view vertical angle in radians
 
---- Return base view distance.
+--- Return the base view distance.
 -- @function [parent=#camera] getBaseViewDistance
 -- @return #number
 
---- Return current view distance.
+--- Return the current view distance.
 -- @function [parent=#camera] getViewDistance
 -- @return #number
 
---- Set view distance.
+--- Set the view distance.
 --- Takes effect on the next frame.
 -- @function [parent=#camera] setViewDistance
 -- @param #number distance View distance in game units
 
---- Get world to local transform for the camera.
+--- Get the world to local transform for the camera.
 -- @function [parent=#camera] getViewTransform
 -- @return openmw.util#Transform
 
---- Get vector from the camera to the world for the given point in viewport.
+--- Get a vector from the camera to the world for the given point in the viewport.
 -- (0, 0) is the top left corner of the screen.
 -- @function [parent=#camera] viewportToWorldVector
 -- @param openmw.util#Vector2 normalizedScreenPos
 -- @return openmw.util#Vector3
 
---- Get vector from the world to the viewport for the given point in world space.
+--- Get a vector from the world to the viewport for the given point in the world space.
 -- (0, 0) is the top left corner of the screen.
 -- The z component of the return value holds the distance from the camera to the position, in world space
 -- @function [parent=#camera] worldToViewportVector

files/lua_api/openmw/core.lua

@@ -7,7 +7,7 @@
 
 
 ---
--- The revision of OpenMW Lua API. It is an integer that is incremented every time the API is changed. See the actual value at the top of the page.
+-- The revision of OpenMW's Lua API. It is an integer that is incremented every time the API is changed. See the actual value at the top of the page.
 -- @field [parent=#core] #number API_REVISION
 
 ---
@@ -160,8 +160,8 @@
 -- Player, actors, items, and statics are game objects.
 -- @type GameObject
 -- @extends #userdata
--- @field #string id A unique id of this object (not record id), can be used as a key in a table.
+-- @field #string id The unique id of this object (not record id), can be used as a key in a table.
--- @field #string contentFile Lower cased file name of the content file that defines this object; nil for dynamically created objects.
+-- @field #string contentFile Lowercase file name of the content file that defines this object; nil for dynamically created objects.
 -- @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 #number scale Object scale.
@@ -174,7 +174,7 @@
 -- @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.
--- @field #string globalVariable Global Variable associated with this object(read only).
+-- @field #string globalVariable Global Variable associated with this object (read only).
 
 
 ---
@@ -193,7 +193,7 @@
 -- @return #boolean
 
 ---
--- Send local event to the object.
+-- Send a local event to the object.
 -- @function [parent=#GameObject] sendEvent
 -- @param self
 -- @param #string eventName
@@ -208,7 +208,7 @@
 -- object:activateBy(self)
 
 ---
--- Add new local script to the object.
+-- Add a new local script to the object.
 -- Can be called only from a global script. Script should be specified in a content
 -- file (omwgame/omwaddon/omwscripts) with a CUSTOM flag. Scripts can not be attached to Statics.
 -- @function [parent=#GameObject] addScript
@@ -239,7 +239,7 @@
 -- @param #number scale Scale desired in game.
 
 ---
--- Moves object to given cell and position.
+-- Moves the object to given cell and position.
 -- Can be called only from a global script.
 -- The effect is not immediate: the position will be updated only in the next
 -- frame. Can be called only from a global script. Enables object if it was disabled.
@@ -252,13 +252,13 @@
 -- @param #TeleportOptions options (optional) Either table @{#TeleportOptions} or @{openmw.util#Transform} rotation.
 
 ---
--- Either table with options or @{openmw.util#Vector3} rotation.
+-- Either a table with options or a @{openmw.util#Vector3} rotation.
 -- @type TeleportOptions
 -- @field openmw.util#Transform rotation New rotation; if missing, then the current rotation is used.
 -- @field #boolean onGround If true, adjust destination position to the ground.
 
 ---
--- Moves object into a container or an inventory. Enables if was disabled.
+-- Moves an object into a container or an inventory. Enables if was disabled.
 -- Can be called only from a global script.
 -- @function [parent=#GameObject] moveInto
 -- @param self
@@ -300,7 +300,7 @@
 -- A cell of the game world.
 -- @type Cell
 -- @field #string name Name of the cell (can be empty string).
--- @field #string displayName Human-readable cell name (takes into account *.cel file localizations). Can be empty string.
+-- @field #string displayName Human-readable cell name (takes into account *.cel file localizations). Can be an empty string.
 -- @field #string id Unique record ID of the cell, based on cell name for interiors and the worldspace for exteriors, or the formID of the cell for ESM4 cells.
 -- @field #string region Region of the cell (can be nil).
 -- @field #boolean isExterior Whether the cell is an exterior cell. "Exterior" means grid of cells where the player can seamless walk from one cell to another without teleports. QuasiExterior (interior with sky) is not an exterior.
@@ -429,14 +429,14 @@
 -- @type Inventory
 
 ---
--- The number of items with given recordId.
+-- The number of items with the given recordId.
 -- @function [parent=#Inventory] countOf
 -- @param self
 -- @param #string recordId
 -- @return #number
 
 ---
--- Get all items of given type from the inventory.
+-- Get all items of the given type from the inventory.
 -- @function [parent=#Inventory] getAll
 -- @param self
 -- @param type (optional) items type (see @{openmw.types#types})
@@ -449,7 +449,7 @@
 -- local weapons = playerInventory:getAll(types.Weapon)
 
 ---
--- Get first item with given recordId from the inventory. Returns nil if not found.
+-- Get first item with the given recordId from the inventory. Returns nil if not found.
 -- @function [parent=#Inventory] find
 -- @param self
 -- @param #string recordId
@@ -470,7 +470,7 @@
 -- @usage inventory:isResolved()
 
 ---
--- Get all items with given recordId from the inventory.
+-- Get all items with the given recordId from the inventory.
 -- @function [parent=#Inventory] findAll
 -- @param self
 -- @param #string recordId
@@ -779,7 +779,7 @@
 -- @field #string affectedAttribute Optional attribute ID
 -- @field #string id Effect id string
 -- @field #string name Localized name of the effect
--- @field #number magnitude current magnitude of the effect. Will be set to 0 when effect is removed or expires.
+-- @field #number magnitude Current magnitude of the effect. Will be set to 0 when the effect is removed or expires.
 -- @field #number magnitudeBase
 -- @field #number magnitudeModifier
 
@@ -854,7 +854,7 @@
 -- @usage core.sound.stopSoundFile("Sound\\test.mp3", object);
 
 ---
--- Check if sound is playing on given object
+-- Check if a sound is playing on the given object
 -- @function [parent=#Sound] isSoundPlaying
 -- @param #string soundId ID of Sound record to check
 -- @param #GameObject object Object on which we want to check sound
@@ -862,7 +862,7 @@
 -- @usage local isPlaying = core.sound.isSoundPlaying("shock bolt", object);
 
 ---
--- Check if sound file is playing on given object
+-- Check if a sound file is playing on the given object
 -- @function [parent=#Sound] isSoundFilePlaying
 -- @param #string fileName Path to sound file in VFS
 -- @param #GameObject object Object on which we want to check sound

files/lua_api/openmw/input.lua

@@ -33,12 +33,12 @@
 
 
 ---
--- Is player idle.
+-- Is the player idle.
 -- @function [parent=#input] isIdle
 -- @return #boolean
 
 ---
--- (DEPRECATED, use getBooleanActionValue) Input bindings can be changed ingame using Options/Controls menu.
+-- (DEPRECATED, use getBooleanActionValue) Input bindings can be changed in-game using Options/Controls menu.
 -- @function [parent=#input] isActionPressed
 -- @param #number actionId One of @{openmw.input#ACTION}
 -- @return #boolean
@@ -104,13 +104,13 @@
 -- @return #string
 
 ---
--- [Deprecated, moved to types.Player] Get state of a control switch. I.e. is player able to move/fight/jump/etc.
+-- [Deprecated, moved to types.Player] Get state of a control switch. I.e. is the player able to move/fight/jump/etc.
 -- @function [parent=#input] getControlSwitch
 -- @param #ControlSwitch key Control type (see @{openmw.input#CONTROL_SWITCH})
 -- @return #boolean
 
 ---
--- [Deprecated, moved to types.Player] Set state of a control switch. I.e. forbid or allow player to move/fight/jump/etc.
+-- [Deprecated, moved to types.Player] Set state of a control switch. I.e. forbid or allow the player to move/fight/jump/etc.
 -- @function [parent=#input] setControlSwitch
 -- @param #ControlSwitch key Control type (see @{openmw.input#CONTROL_SWITCH})
 -- @param #boolean value
@@ -127,7 +127,7 @@
 -- @field [parent=#CONTROL_SWITCH] #ControlSwitch Looking Ability to change view direction
 -- @field [parent=#CONTROL_SWITCH] #ControlSwitch Magic Ability to use magic
 -- @field [parent=#CONTROL_SWITCH] #ControlSwitch ViewMode Ability to toggle 1st/3rd person view
--- @field [parent=#CONTROL_SWITCH] #ControlSwitch VanityMode Vanity view if player doesn't touch controls for a long time
+-- @field [parent=#CONTROL_SWITCH] #ControlSwitch VanityMode Vanity view if the player doesn't touch controls for a long time
 
 ---
 -- [Deprecated, moved to types.Player] Values that can be used with getControlSwitch/setControlSwitch.

files/lua_api/openmw/markup.lua

@@ -7,15 +7,15 @@
 
 
 ---
--- Convert YAML data to Lua object
+-- Convert YAML data to a Lua object
 -- @function [parent=#markup] decodeYaml
 -- @param #string inputData Data to decode. It has such limitations:
 --
 --   1. YAML format of [version 1.2](https://yaml.org/spec/1.2.2) is used.
 --   2. Map keys should be scalar values (strings, booleans, numbers).
 --   3. YAML tag system is not supported.
---   4. If scalar is quoted, it is treated like a string.
+--   4. If a scalar is quoted, it is treated like a string.
--- Othewise type deduction works according to YAML 1.2 [Core Schema](https://yaml.org/spec/1.2.2/#103-core-schema).
+-- Otherwise, type deduction works according to YAML 1.2 [Core Schema](https://yaml.org/spec/1.2.2/#103-core-schema).
 --   5. Circular dependencies between YAML nodes are not allowed.
 --   6. Lua 5.1 does not have integer numbers - all numeric scalars use a #number type (which use a floating point).
 --   7. Integer scalars numbers values are limited by the "int" range. Use floating point notation for larger number in YAML files.
@@ -25,9 +25,9 @@
 -- print(result["x"])
 
 ---
--- Load YAML file from VFS to Lua object. Conventions are the same as in @{#markup.decodeYaml}.
+-- Load a YAML file from the VFS to Lua object. Conventions are the same as in @{#markup.decodeYaml}.
 -- @function [parent=#markup] loadYaml
--- @param #string fileName YAML file path in VFS.
+-- @param #string fileName YAML file path in the VFS.
 -- @return #any Lua object (can be table or scalar value).
 -- @usage -- file contains '{ "x": 1 }' data
 -- local result = markup.loadYaml('test.yaml');

files/lua_api/openmw/nearby.lua

@@ -75,7 +75,7 @@
 --  NOTE: currently `ignore` is not supported if `radius>0`.
 
 ---
--- Cast ray from one point to another and return the first collision.
+-- Cast a 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.
@@ -95,10 +95,13 @@
 -- @field #any ignore A @{openmw.core#GameObject} or @{openmw.core#ObjectList} to ignore while doing the ray cast
 
 ---
--- Cast ray from one point to another and find the first visual intersection with anything in the scene.
+-- Cast a ray from one point to another and find the first visual intersection with anything in the scene.
--- As opposite to `castRay` can find an intersection with an object without collisions.
+-- Unlike `castRay`, `castRenderingRay` can find an intersection with an object without collisions.
--- In order to avoid threading issues can be used only in player scripts only in `onFrame` or
+-- To avoid threading issues, `castRenderingRay` can only be used in:
--- in engine handlers for user input. In other cases use `asyncCastRenderingRay` instead.
+-- - The `onFrame` engine handler.
+-- - Engine handlers for user input.
+-- - Callbacks provided to @{openmw.input#registerActionHandler}
+-- In other cases, use `asyncCastRenderingRay` instead.
 -- @function [parent=#nearby] castRenderingRay
 -- @param openmw.util#Vector3 from Start point of the ray.
 -- @param openmw.util#Vector3 to End point of the ray.
@@ -106,7 +109,7 @@
 -- @return #RayCastingResult
 
 ---
--- Asynchronously cast ray from one point to another and find the first visual intersection with anything in the scene.
+-- Asynchronously cast a ray from one point to another and find the first visual intersection with anything in the scene.
 -- @function [parent=#nearby] asyncCastRenderingRay
 -- @param openmw.async#Callback callback The callback to pass the result to (should accept a single argument @{openmw.nearby#RayCastingResult}).
 -- @param openmw.util#Vector3 from Start point of the ray.
@@ -202,7 +205,7 @@
 -- type to cover the whole active grid).
 
 ---
--- Find path over navigation mesh from source to destination with given options. Result is unstable since navigation
+-- Find a path over the navigation mesh from the source to the destination with the given options. Result is unstable since navigation
 -- mesh generation is asynchronous.
 -- @function [parent=#nearby] findPath
 -- @param openmw.util#Vector3 source Initial path position.
@@ -222,7 +225,7 @@
 -- })
 
 ---
--- Returns random location on navigation mesh within the reach of specified location.
+-- Returns a random location on the navigation mesh within the reach of the specified location.
 -- The location is not exactly constrained by the circle, but it limits the area.
 -- @function [parent=#nearby] findRandomPointAroundCircle
 -- @param openmw.util#Vector3 position Center of the search circle.

files/lua_api/openmw/storage.lua

@@ -57,14 +57,14 @@
 -- @type StorageSection
 
 ---
--- Get value by a string key; if value is a table makes it readonly.
+-- Get a value by a string key; if the value is a table it is readonly.
 -- @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.
+-- Get a value by a string key; if the value is a table it returns a copy.
 -- @function [parent=#StorageSection] getCopy
 -- @param self
 -- @param #string key
@@ -105,8 +105,8 @@
 -- myModData:removeOnExit()
 
 ---
--- Set the life time of given storage section.
+-- Set the lifetime of given storage section.
--- New sections initially have a Persistent life time.
+-- New sections initially have a Persistent lifetime.
 -- This function can be used for a global storage section from a global script or for a player storage section from a player or menu script.
 -- @function [parent=#StorageSection] setLifeTime
 -- @param self
@@ -117,7 +117,7 @@
 -- myModData:setLifeTime(storage.LIFE_TIME.Temporary)
 
 ---
--- Set value by a string key; can not be used for global storage from a local script.
+-- Set a value by a string key; can not be used for global storage from a local script.
 -- @function [parent=#StorageSection] set
 -- @param self
 -- @param #string key

files/lua_api/openmw/types.lua

@@ -193,7 +193,7 @@
 -- @param openmw.core#Spell spell Spell (can be nil)
 
 ---
--- Clears the actor's selected castable(spell or enchanted item)
+-- Clears the actor's selected castable (spell or enchanted item)
 -- @function [parent=#Actor] clearSelectedCastable
 -- @param openmw.core#GameObject actor
 
@@ -251,7 +251,7 @@
 -- @param #string effectId effect ID
 -- @param #string extraParam Optional skill or attribute ID
 
---- (Note that using this function will override and conflict with all other sources of this effect, you probably want to use @{#ActorActiveEffects.modify} instead, this function is provided for mwscript parity only)
+--- (Note that using this function will override and conflict with all other sources of this effect. You probably want to use @{#ActorActiveEffects.modify} instead, this function is provided for mwscript parity only)
 -- Permanently modifies the magnitude of an active effect to be exactly equal to the provided value.
 -- Note that although the modification is permanent, the magnitude will not stay equal to the value if any active spells with this effects are added/removed.
 -- Also see the notes on @{#ActorActiveEffects.modify}
@@ -1000,7 +1000,7 @@
 ---
 -- Expel NPC from given faction.
 -- Throws an exception if there is no such faction.
--- Note: expelled NPC still keeps his rank and reputation in faction, he just get an additonal flag for given faction.
+-- Note: the expelled NPC still keeps their rank and reputation in the faction, they just get an additional flag for the given faction.
 -- @function [parent=#NPC] expel
 -- @param openmw.core#GameObject actor NPC object
 -- @param #string faction Faction ID
@@ -1459,7 +1459,7 @@
 -- @field #number enchantCapacity
 
 ---
--- Creates a @{#ArmorRecord} without adding it to the world database, for the armor to appear correctly on the body, make sure to use a template as described below.
+-- Creates an @{#ArmorRecord} without adding it to the world database, for the armor to appear correctly on the body, make sure to use a template as described below.
 -- Use @{openmw_world#(world).createRecord} to add the record to the world.
 -- @function [parent=#Armor] createRecordDraft
 -- @param #ArmorRecord armor A Lua table with the fields of a ArmorRecord, with an additional field `template` that accepts a @{#ArmorRecord} as a base.
@@ -2167,7 +2167,7 @@
 -- @field #string mwscript MWScript on this activator (can be nil)
 
 ---
--- Creates a @{#ActivatorRecord} without adding it to the world database.
+-- Creates an @{#ActivatorRecord} without adding it to the world database.
 -- Use @{openmw_world#(world).createRecord} to add the record to the world.
 -- @function [parent=#Activator] createRecordDraft
 -- @param #ActivatorRecord activator A Lua table with the fields of a ActivatorRecord, with an optional field `template` that accepts a @{#ActivatorRecord} as a base.

files/lua_api/openmw/vfs.lua

@@ -19,8 +19,8 @@
 -- @return #nil, #string nil plus the error message in case of any error.
 
 ---
--- Get an iterator function to fetch the next line from given file.
+-- Get an iterator function to fetch the next line from a given file.
--- Throws an exception if file is closed.
+-- Throws an exception if the file is closed.
 --
 -- Hint: since garbage collection works once per frame,
 -- you will get the whole file in RAM if you read it in one frame.
@@ -36,8 +36,8 @@
 -- end
 
 ---
--- Set new position in file.
+-- Set new position in a file.
--- Throws an exception if file is closed or seek base is incorrect.
+-- Throws an exception if the file is closed or seek base is incorrect.
 -- @function [parent=#FileHandle] seek
 -- @param self
 -- @param #string whence Seek base (optional, "cur" by default). Can be:
@@ -59,8 +59,8 @@
 -- print(f:seek("end"));
 
 ---
--- Read data from file to strings.
+-- Read data from a file to strings.
--- Throws an exception if file is closed, if there is too many arguments or if an invalid format encountered.
+-- Throws an exception if the file is closed, if there are too many arguments or if an invalid format is encountered.
 --
 -- Hint: since garbage collection works once per frame,
 -- you will get the whole file in RAM if you read it in one frame.
@@ -94,7 +94,7 @@
 -- -- prints(1, nil)
 
 ---
--- Check if file exists in VFS
+-- Check if a file exists in VFS
 -- @function [parent=#vfs] fileExists
 -- @param #string fileName Path to file in VFS
 -- @return #boolean (true - exists, false - does not exist)
@@ -115,9 +115,9 @@
 -- end
 
 ---
--- Get an iterator function to fetch the next line from file with given path.
+-- Get an iterator function to fetch the next line from a file with the given path.
--- Throws an exception if file is closed or file with given path does not exist.
+-- Throws an exception if the file is closed or the file with the given path does not exist.
--- Closes file automatically when it fails to read any more bytes.
+-- Closes the file automatically when it fails to read any more bytes.
 --
 -- Hint: since garbage collection works once per frame,
 -- you will get the whole file in RAM if you read it in one frame.
@@ -132,7 +132,7 @@
 -- end
 
 ---
--- Get iterator function to fetch file names with given path prefix from VFS
+-- Get an iterator function to fetch file names with given path prefix from the VFS
 -- @function [parent=#vfs] pathsWithPrefix
 -- @param #string path Path prefix
 -- @return #function Function to get next file name

files/lua_api/openmw/world.lua

@@ -129,7 +129,7 @@
 -- @param #string tag (optional, empty string by default) The game will be paused until `unpause` is called with the same tag.
 
 ---
--- Remove given tag from the list of pause tags. Resume the game starting from the next frame if the list became empty.
+-- Remove the given tag from the list of pause tags. Resume the game starting from the next frame if the list became empty.
 -- @function [parent=#world] unpause
 -- @param #string tag (optional, empty string by default) Needed to undo `pause` called with this tag.