Merge branch 'lua-docs-minor-grammar-fixes' into 'master'

Minor grammar fixes for `ambient` `async` and `animation` packages

See merge request OpenMW/openmw!4359

files/lua_api/openmw/ambient.lua

@@ -1,6 +1,6 @@
 ---
--- `openmw.ambient` controls background sounds, specific to given player (2D-sounds).
+-- `openmw.ambient` controls background 2D sounds specific to a given player.
--- Can be used only by menu scripts and local scripts, that are attached to a player.
+-- Can be used only by menu scripts and local scripts that are attached to a player.
 -- @module ambient
 -- @usage local ambient = require('openmw.ambient')
 
@@ -12,11 +12,11 @@
 -- @param #string soundId ID of Sound record to play
 -- @param #table options An optional table with additional optional arguments. Can contain:
 --
---   * `timeOffset` - a floating point number >= 0, to skip some time (in seconds) from beginning of sound file (default: 0);
+--   * `timeOffset` - a floating point number >= 0, to skip some time (in seconds) from the beginning of the sound (default: 0);
---   * `volume` - a floating point number >= 0, to set a sound volume (default: 1);
+--   * `volume` - a floating point number >= 0, to set the sound's volume (default: 1);
---   * `pitch` - a floating point number >= 0, to set a sound pitch (default: 1);
+--   * `pitch` - a floating point number >= 0, to set the sound's pitch (default: 1);
---   * `scale` - a boolean, to set if sound pitch should be scaled by simulation time scaling (default: true);
+--   * `scale` - a boolean, to set if the sound's pitch should be scaled by simulation time scaling (default: true);
---   * `loop` - a boolean, to set if sound should be repeated when it ends (default: false);
+--   * `loop` - a boolean, to set if the sound should be repeated when it ends (default: false);
 -- @usage local params = {
 --    timeOffset=0.1
 --    volume=0.3,
@@ -29,14 +29,14 @@
 ---
 -- Play a 2D sound file
 -- @function [parent=#ambient] playSoundFile
--- @param #string fileName Path to sound file in VFS
+-- @param #string fileName Path to a sound file in VFS
 -- @param #table options An optional table with additional optional arguments. Can contain:
 --
---   * `timeOffset` - a floating point number >= 0, to skip some time (in seconds) from beginning of sound file (default: 0);
+--   * `timeOffset` - a floating point number >= 0, to skip some time (in seconds) from the beginning of the sound file (default: 0);
---   * `volume` - a floating point number >= 0, to set a sound volume (default: 1);
+--   * `volume` - a floating point number >= 0, to set the sound's volume (default: 1);
---   * `pitch` - a floating point number >= 0, to set a sound pitch (default: 1);
+--   * `pitch` - a floating point number >= 0, to set the sound's pitch (default: 1);
---   * `scale` - a boolean, to set if sound pitch should be scaled by simulation time scaling (default: true);
+--   * `scale` - a boolean, to set if the sound's pitch should be scaled by simulation time scaling (default: true);
---   * `loop` - a boolean, to set if sound should be repeated when it ends (default: false);
+--   * `loop` - a boolean, to set if the sound should be repeated when it ends (default: false);
 -- @usage local params = {
 --    timeOffset=0.1
 --    volume=0.3,
@@ -55,37 +55,37 @@
 ---
 -- Stop a sound file
 -- @function [parent=#ambient] stopSoundFile
--- @param #string fileName Path to sound file in VFS
+-- @param #string fileName Path to a sound file in VFS
 -- @usage ambient.stopSoundFile("Sound\\test.mp3");
 
 ---
--- Check if sound is playing
+-- Check if a sound is playing
 -- @function [parent=#ambient] isSoundPlaying
 -- @param #string soundId ID of Sound record to check
 -- @return #boolean
 -- @usage local isPlaying = ambient.isSoundPlaying("shock bolt");
 
 ---
--- Check if sound file is playing
+-- Check if a sound file is playing
 -- @function [parent=#ambient] isSoundFilePlaying
--- @param #string fileName Path to sound file in VFS
+-- @param #string fileName Path to a sound file in VFS
 -- @return #boolean
 -- @usage local isPlaying = ambient.isSoundFilePlaying("Sound\\test.mp3");
 
 ---
 -- Play a sound file as a music track
 -- @function [parent=#ambient] streamMusic
--- @param #string fileName Path to file in VFS
+-- @param #string fileName Path to a file in VFS
 -- @param #table options An optional table with additional optional arguments. Can contain:
 --
---   * `fadeOut` - a floating point number >= 0, time (in seconds) to fade out current track before playing this one (default 1.0);
+--   * `fadeOut` - a floating point number >= 0, time (in seconds) to fade out the current track before playing this one (default 1.0);
 -- @usage local params = {
 --    fadeOut=2.0
 -- };
 -- ambient.streamMusic("Music\\Test\\Test.mp3", params)
 
 ---
--- Stop to play current music
+-- Stop the currently playing music
 -- @function [parent=#ambient] stopMusic
 -- @usage ambient.stopMusic();
 
@@ -98,7 +98,7 @@
 ---
 -- Play an ambient voiceover.
 -- @function [parent=#ambient] say
--- @param #string fileName Path to sound file in VFS
+-- @param #string fileName Path to a sound file in VFS
 -- @param #string text Subtitle text (optional)
 -- @usage -- play voiceover and print messagebox
 -- ambient.say("Sound\\Vo\\Misc\\voice.mp3", "Subtitle text")
@@ -108,7 +108,7 @@
 ---
 -- Stop an ambient voiceover
 -- @function [parent=#ambient] stopSay
--- @param #string fileName Path to sound file in VFS
+-- @param #string fileName Path to a sound file in VFS
 -- @usage ambient.stopSay();
 
 ---

files/lua_api/openmw/animation.lua

@@ -1,5 +1,5 @@
 ---
--- `openmw.animation` defines functions that allow control of character animations
+-- `openmw.animation` defines functions that allow control of character animations.
 -- Note that for some methods, such as @{openmw.animation#playBlended} you should use the associated methods on the 
 -- [AnimationController](interface_animation.html) interface rather than invoking this API directly.
 -- @module animation
@@ -55,7 +55,7 @@
 -- @return #boolean
 
 ---
--- Skips animations for one frame, equivalent to mwscript's SkipAnim
+-- Skips animations for one frame, equivalent to mwscript's SkipAnim.
 -- Can be used only in local scripts on self.
 -- @function [parent=#animation] skipAnimationThisFrame
 -- @param openmw.core#GameObject actor
@@ -98,7 +98,7 @@
 
 
 ---
--- Cancels and removes the animation group from the list of active animations
+-- Cancels and removes the animation group from the list of active animations.
 -- Can be used only in local scripts on self.
 -- @function [parent=#animation] cancel
 -- @param openmw.core#GameObject actor

files/lua_api/openmw/async.lua

@@ -1,5 +1,5 @@
 ---
--- `openmw.async` contains timers and coroutine utils. All functions require
+-- `openmw.async` contains timers and coroutine utilities. All functions require
 -- the package itself as a first argument.
 -- @module async
 -- @usage local async = require('openmw.async')
@@ -16,7 +16,7 @@
 
 ---
 -- Calls callback(arg) in `delay` simulation seconds.
--- Callback must be registered in advance.
+-- The callback must be registered in advance.
 -- @function [parent=#async] newSimulationTimer
 -- @param self
 -- @param #number delay
@@ -25,7 +25,7 @@
 
 ---
 -- Calls callback(arg) in `delay` game seconds.
--- Callback must be registered in advance.
+-- The callback must be registered in advance.
 -- @function [parent=#async] newGameTimer
 -- @param self
 -- @param #number delay
@@ -49,7 +49,7 @@
 -- @param #function func
 
 ---
--- Wraps Lua function with `Callback` object that can be used in async API calls.
+-- Wraps a Lua function with a `Callback` object that can be used in async API calls.
 -- @function [parent=#async] callback
 -- @param self
 -- @param #function func