Sync LuaDocumentation.xml with 'Lua for SM5'

The LuaDocumentation.xml in the StepMania repository and
quietly-turning's 'Lua for SM5' diverged over time. This commit pulls in
a couple of documentation improvements from 'Lua for SM5'.

- Add documentation for previously undocumented functions
- Improved descriptions
- More crosslinking

Docs/Luadoc/LuaDocumentation.xml

@@ -162,7 +162,7 @@ save yourself some time, copy this for undocumented things:
 		Creates a RageBezier2D for you to use.  Make sure you destroy the RageBezier2D when you're done with it, or you will have a memory leak.
 	</Function>
 	<Function name='create_spline' return='CubicSplineN' arguments=''>
-		Creates a CubicSplineN for you to use.  Make sure you destroy the CubicSplineN when you're done with it, or you will have a memory leak.
+		Creates a CubicSplineN for you to use.  Make sure you <Link class="CubicSplineN" function='destroy'>destroy</Link> the CubicSplineN when you're done with it, or you will have a memory leak.
 	</Function>
 	<Function name='CustomDifficultyToColor' theme='_fallback' return='color' arguments='string cd'>
 		[02 Colors.lua]
@@ -467,10 +467,6 @@ save yourself some time, copy this for undocumented things:
 	<Function name='MissCombo' theme='_fallback' return='int' arguments=''>
 		[03 Gameplay.lua] Returns the value to start showing the miss combo at.
 	</Function>
-	<Function name='module' return='void' arguments='string name, ...'>
-		Creates a module.<br />
-		<code>module</code> is a core function of Lua's basic library; see the Lua manual for more details.
-	</Function>
 	<Function name='MonthOfYear' return='int' arguments=''>
 		Returns the current month of the year in the range <code>0</code>-<code>11</code>.
 	</Function>
@@ -692,6 +688,14 @@ save yourself some time, copy this for undocumented things:
 	<Function name='StandardDecorationFromFileOptional' theme='_fallback' return='Actor' arguments='string sMetricsName, string sFileName'>
 		[02 ActorDef.lua]
 	</Function>
+	<Function name='StringToBlend' theme='_fallback' return='string' arguments='string s'>
+		[01 Alias.lua] Given the short form of a <Link class='ENUM' function='BlendMode' /> string, returns the full version of the string.<br />
+		Returns <code>nil</code> if the string passed in does not match any valid BlendModes.
+<pre><code>
+local b = StringToBlend("AlphaMask")
+Trace(b)  -- "BlendMode_AlphaMask"
+</code></pre>
+	</Function>
 	<Function name='tableshuffle' theme='_fallback' return='table' arguments='table t'>
 		[02 Utilities.lua] Returns a shuffled version of <code>t</code>.
 	</Function>
@@ -826,11 +830,11 @@ local playable_steps = SongUtil.GetPlayableSteps(song)
 		Returns the Y Offset of a note in column <code>iCol</code> at beat <code>fNoteBeat</code> for the provided PlayerState. Y Offset is affected by Speed mods and Accel mods, and impacts most other arrow effects.
 	</Function>
 	<Function name='GetYPos' return='float' arguments='PlayerState ps, int iCol, float fYOffset, float fYReverseOffsetPixels'>
-		Returns the Y position of a note in column <code>iCol</code> with a Y offset of <code>fYOffset</code> for the provided PlayerState.<br/>
+		Returns the Y position of a note in column <code>iCol</code> with a Y offset of <code>fYOffset</code> for the provided PlayerState.<br />
 		<code>fYReverseOffsetPixels</code> is the separation between targets with and without reverse. This argument is optional and will pull defaults from the metrics for <code>[Player]</code>
 	</Function>
 	<Function name='GetYOffsetFromYPos' return='float' arguments='PlayerState ps, int iCol, float fYPos, float fYReverseOffsetPixels'>
-		Returns the Y offset of a note in column <code>iCol</code> with a Y position of <code>fYPos</code> for the provided PlayerState.<br/>
+		Returns the Y offset of a note in column <code>iCol</code> with a Y position of <code>fYPos</code> for the provided PlayerState.<br />
 		<code>fYReverseOffsetPixels</code> is the separation between targets with and without reverse. This argument is optional and will pull defaults from the metrics for <code>[Player]</code>
 	</Function>
 	<Function name='GetXPos' return='float' arguments='PlayerState ps, int iCol, float fYOffset'>
@@ -846,18 +850,18 @@ local playable_steps = SongUtil.GetPlayableSteps(song)
 		Returns the Y rotation of a note with a Y offset of <code>fYOffset</code> for the provided PlayerState.
 	</Function>
 	<Function name='GetRotationZ' return='float' arguments='PlayerState ps, float fNoteBeat, bool bIsHoldHead'>
-		Returns the Z rotation of a note at beat <code>fNoteBeat</code> for the provided PlayerState.<br/>
+		Returns the Z rotation of a note at beat <code>fNoteBeat</code> for the provided PlayerState.<br />
 		<code>bIsHoldHead</code> is an optional argument which defaults to false. If true, this function will return <code>0</code> if the [PlayerOptions] modifier <code>DizzyHolds</code> is off.
 	</Function>
 	<Function name='ReceptorGetRotationZ' return='float' arguments='PlayerState ps'>
 		Returns the Z rotation of the receptors for the provided PlayerState.
 	</Function>
 	<Function name='GetAlpha' return='float' arguments='PlayerState ps, int iCol, float fYOffset, float fPercentFadeToFail, float fYReverseOffsetPixels, float fDrawDistanceBeforeTargetsPixels, float fFadeInPercentOfDrawFar'>
-		Returns the Alpha of a note in column <code>iCol</code> with a Y offset of <code>fYOffset</code> for the provided PlayerState.<br/>
+		Returns the Alpha of a note in column <code>iCol</code> with a Y offset of <code>fYOffset</code> for the provided PlayerState.<br />
-		<code>fPercentFadeToFail</code> is optional and defaults to -1.<br/>
+		<code>fPercentFadeToFail</code> is optional and defaults to -1.<br />
-		<code>fYReverseOffsetPixels</code> is the separation between targets with and without reverse. This argument is optional and will pull defaults from the metrics for <code>[Player]</code><br/>
+		<code>fYReverseOffsetPixels</code> is the separation between targets with and without reverse. This argument is optional and will pull defaults from the metrics for <code>[Player]</code><br />
-		<code>fDrawDistanceBeforeTargetsPixels</code> is optional and will pull defaults from the <code>[Player]</code> metric <code>DrawDistanceBeforeTargetsPixels</code><br/>
+		<code>fDrawDistanceBeforeTargetsPixels</code> is optional and will pull defaults from the <code>[Player]</code> metric <code>DrawDistanceBeforeTargetsPixels</code><br />
-		<code>fFadeInPercentOfDrawFar</code> is optional and will pull defaults from the <code>[NoteField]</code> metric <code>FadeBeforeTargetsPercent</code><br/>
+		<code>fFadeInPercentOfDrawFar</code> is optional and will pull defaults from the <code>[NoteField]</code> metric <code>FadeBeforeTargetsPercent</code><br />
 	</Function>
 	<Function name='GetGlow' return='float' arguments='PlayerState ps, int iCol, float fYOffset, float fPercentFadeToFail, float fYReverseOffsetPixels, float fDrawDistanceBeforeTargetsPixels, float fFadeInPercentOfDrawFar'>
 		Returns the Glow of a note in column <code>iCol</code> with a Y offset of <code>fYOffset</code> for the provided PlayerState. The arguments are the same as for GetAlpha.
@@ -872,7 +876,8 @@ local playable_steps = SongUtil.GetPlayableSteps(song)
 		Returns the zoom of a note for the provided PlayerState.
 	</Function>
 	<Function name='GetFrameWidthScale' return='float' arguments='PlayerState ps, float fYOffset, float fOverlappedTime'>
-		Returns the FrameWidthScale of a hold part with a Y offset of <code>fYOffset</code> for the provided PlayerState.<br/> <code>fOverlappedTime</code> is optional and will default to 0.
+		Returns the FrameWidthScale of a hold part with a Y offset of <code>fYOffset</code> for the provided PlayerState.<br />
+		<code>fOverlappedTime</code> is optional and will default to 0.
 	</Function>
 </Namespace>
 <Namespace name='Enum'>
@@ -929,12 +934,12 @@ local n = r['PlayerNumber_P2']
 		If unsuccessful, it returns two values: <code>nil</code> and <code>"error"</code>.
 	</Function>
 	<Function name='ReportScriptError' return='void' arguments='string error, string error_type'>
-		Reports the error through the error reporting system.<br/>
+		Reports the error through the error reporting system.<br />
-		<code>error</code> is optional and defaults to "Script error occurred.".<br/>
+		<code>error</code> is optional and defaults to "Script error occurred.".<br />
 		<code>error_type</code> is optional and defaults to "LUA_ERROR".  Errors of type "LUA_ERROR" will be shown in-game if the <code>ShowThemeErrors</code> preference is enabled. A dialog will not appear for an <code>error_type</code> the user has chosen to ignore.
 	</Function>
 	<Function name='RunWithThreadVariables' return='int' arguments='function func, table t, ...'>
-		Calls <code>func(...)</code> with LuaThreadVariables set according to the keys and values of <code>t</code>, and returns the return values of <code>func()</code>.<br/>
+		Calls <code>func(...)</code> with LuaThreadVariables set according to the keys and values of <code>t</code>, and returns the return values of <code>func()</code>.<br />
 		For example, if <code>t</code> is <code>{x=12}</code>, calling <code>Var "x"</code> from <code>func</code> will return 12.
 	</Function>
 	<Function name='Trace' return='void' arguments='string sString'>
@@ -1178,7 +1183,7 @@ local n = r['PlayerNumber_P2']
 		See <a href="https://github.com/itgmania/itgmania/blob/HEAD/Docs/Themerdocs/effect_colors.txt" target="_blank" rel="noopener noreferrer">Docs/Themerdocs/effect_colors.txt</a>
 		for an example.
 	</Function>
-	<Function name='diffusebottomedge' return='void' arguments=''>
+	<Function name='diffusebottomedge' return='void' arguments='color c'>
 		Sets the Actor's bottom edge color to <code>c</code>.
 	</Function>
 	<Function name='diffusecolor' return='void' arguments='color c'>
@@ -1246,12 +1251,9 @@ local n = r['PlayerNumber_P2']
 		Set the Actor's effect period to <code>fTime</code>.
 	</Function>
 	<Function name='effecttiming' return='void' arguments='float ramp_to_half, float hold_at_half, float ramp_to_full, float hold_at_zero, float hold_at_full'>
-		Set the Actor's effect timing.<br />
+		Set the Actor's effect timing.  The effect timing controls how long it takes an effect to cycle and how long it spends in each phase.<br /><br />
-		hold_at_zero is before hold_at_full in the argument list for compatibility.  A future version will probably swap them because it makes more sense to have hold_at_full come before hold_at_zero.<br />
 		All effect timings must be greater than or equal to zero, at least one of them must be greater than zero.<br />
-		The effect timing controls how long it takes an effect to cycle and how long it spends in each phase.<br />
 		Depending on the effect clock, the actor's time into effect is updated every frame.  That time is then translated into a percent_through_effect using the parameters to this function.<br />
-		<br />
 		ramp_to_half is the amount of time for percent_through_effect to reach 0.5.<br />
 		hold_at_half is the amount of time percent_through_effect will stay at 0.5.<br />
 		ramp_to_full is the amount of time percent_through_effect will take to go from 0.5 to 1.0.<br />
@@ -1259,8 +1261,8 @@ local n = r['PlayerNumber_P2']
 		After reaching the end of hold_at_full, percent_through_effect stays at 0 until hold_at_zero is over.<br />
 		<br />
 		The different effects use percent_through_effect in different ways.  Some use it to calculate percent_between_colors with this sine wave:  sin((percent_through_effect + 0.25f) * 2 * PI ) / 2 + 0.5f<br />
-		Some effects check the internal bool blink_on.  blink_on is true if percent_through_effect is greater than 0.5 and false if percent_through_effect is less than or equal to 0.5.<br />
+		Some effects check the internal bool blink_on.  blink_on is true if percent_through_effect is greater than 0.5 and false if percent_through_effect is less than or equal to 0.5.<br /><br />
-		Check the effect functions for individual explanations:  diffuseblink, diffuseshift, glowblink, glowshift, glowramp, rainbow, wag, bounce, bob, pulse, spin, vibrate.
+		Check the effect functions for individual explanations:  <Link  function="diffuseblink" />, <Link  function="diffuseshift" />, <Link  function="glowblink" />, <Link  function="glowshift" />, <Link  function="glowramp" />, <Link  function="rainbow" />, <Link  function="wag" />, <Link  function="bounce" />, <Link  function="bob" />, <Link  function="pulse" />, <Link  function="spin" />, <Link  function="vibrate" />.
 	</Function>
 	<Function name='effect_hold_at_full' return='void' arguments='float hold_at_full'>
 		Set the hold_at_full part of the effect timing while leaving the others unchanged.
@@ -1377,7 +1379,8 @@ local n = r['PlayerNumber_P2']
 		for an example.
 	</Function>
 	<Function name='halign' return='void' arguments='float fAlign'>
-		Set the fractional horizontal alignment of the Actor according to <code>fAlign</code> which should be a float in the range 0..1. An alignment of 0 is left aligned while an alignment of 1 is right aligned. See <Link function='horizalign' /> for the common case.
+		Set the fractional horizontal alignment of the Actor according to <code>fAlign</code> which should be a float in the range 0..1. An alignment of 0 is left-aligned while an alignment of 1 is right-aligned.<br />
+		Use <Link function='horizalign' /> for the common case.
 	</Function>
 	<Function name='heading' return='void' arguments='float fHeading'>
 		Sets the heading of this Actor to <code>fHeading</code>.
@@ -1392,7 +1395,14 @@ local n = r['PlayerNumber_P2']
 		[02 Actor.lua] "Hide if <code>b</code> is <code>true</code>, but don't unhide if <code>b</code> is <code>false</code>."
 	</Function>
 	<Function name='horizalign' return='void' arguments='HorizAlign align'>
-		Set the horizontal alignment of the Actor according to <code>align</code>. See <Link function='halign' /> for fractional alignment.
+		Set the <Link class='ENUM' function='HorizAlign'/> of the Actor according to <code>align</code>.<br />
+<pre><code>
+local spr = LoadActor('awesome.png')
+spr.InitCommand=function(self)
+	self:horizalign('HorizAlign_Left')
+end
+</code></pre>
+		Use <Link function='halign' /> for fractional alignment.
 	</Function>
 	<Function name='hurrytweening' return='void' arguments='float factor'>
 		Hurries up an Actor's tweening by <code>factor</code>.
@@ -1530,10 +1540,18 @@ local n = r['PlayerNumber_P2']
 		It's usually more convenient to use <Link function='linear' />, <Link function='accelerate' />, <Link function='decelerate' />, or <Link function='spring' /> rather than using Actor:tween() directly.
 	</Function>
 	<Function name='valign' return='void' arguments='float fAlign'>
-		Set the fractional vertical alignment of the Actor according to <code>fAlign</code> which should be a float in the range 0..1. An alignment of 0 is top aligned while an alignment of 1 is bottom aligned. See <Link function="vertalign" /> for the common case.
+		Set the fractional vertical alignment of the Actor according to <code>fAlign</code> which should be a float in the range 0..1. An alignment of 0 is top-aligned while an alignment of 1 is bottom-aligned.<br />
+		Use <Link function="vertalign" /> for the common case.
 	</Function>
 	<Function name='vertalign' return='void' arguments='VertAlign align'>
-		Set the vertical alignment of the Actor according to <code>align</code>. See <Link function="valign" /> for fractional alignment.
+		Set the <Link class='ENUM' function='VertAlign' /> of the Actor according to <code>align</code>.<br />
+<pre><code>
+local spr = LoadActor('awesome.png')
+spr.InitCommand=function(self)
+	self:vertalign('VertAlign_Bottom')
+end
+</code></pre>
+		Use <Link function="valign" /> for fractional alignment.
 	</Function>
 	<Function name='vibrate' return='void' arguments=''>
 		Makes the Actor vibrate violently. Can use <Link function='effectmagnitude' /> to define different vibration behavior.
@@ -1794,7 +1812,7 @@ return af
 		Clears all the textures from the ActorMultiTexture.
 	</Function>
 	<Function name='SetEffectMode' return='void' arguments='EffectMode em'>
-		Sets the EffectMode on the ActorMultiTexture.
+		Sets the <Link class='ENUM' function='EffectMode' /> on the ActorMultiTexture.
 	</Function>
 	<Function name='SetSizeFromTexture' return='void' arguments='RageTexture tex'>
 		Sets the size of the ActorMultiTexture from the specified texture.
@@ -1803,7 +1821,7 @@ return af
 		Sets the coordinates of the ActorMultiTexture.
 	</Function>
 	<Function name='SetTextureMode' return='void' arguments='int iIndex, TextureMode tm'>
-		Sets a TextureMode on the specified index.
+		Sets a <Link class='ENUM' function='TextureMode' /> on the specified index.
 	</Function>
 </Class>
 <Class name='ActorMultiVertex' grouping='Actor'>
@@ -1940,10 +1958,10 @@ self:SetDrawState{First= 3, Num= 4}
 		Returns the ActorMultiVertex's texture.
 	</Function>
 	<Function name='SetEffectMode' return='void' arguments='EffectMode em'>
-		Sets the <Link class='ENUM' function='EffectMode'>EffectMode</Link> of the ActorMultiVertex.
+		Sets the <Link class='ENUM' function='EffectMode' /> of the ActorMultiVertex.
 	</Function>
 	<Function name='SetTextureMode' return='void' arguments='TextureMode tm'>
-		Sets the <Link class='ENUM' function='TextureMode'>TextureMode</Link> of the ActorMultiVertex.
+		Sets the <Link class='ENUM' function='TextureMode' /> of the ActorMultiVertex.
 	</Function>
 	<Function name='SetLineWidth' return='void' arguments='float width'>
 		Sets the width of the line for DrawMode_LineStrip.
@@ -2177,7 +2195,7 @@ Def.Sound{
 <Class name='BitmapText' grouping='Actor'>
 	<Description>
 		<em>BitmapText</em> actors are used to display text on-screen.<br />
-		The font can be specified using the <code>Font</code> attribute. It takes a font name a string,
+		The font can be specified using the <code>Font</code> attribute. It takes a font name as a string,
 		pathed relative to the current theme's <code>./Fonts/</code> directory.<br />
 		StepMania expects fonts to be formatted as spritesheets with accompanying ini files.
 		These can be generated from ttf files using <em>Texture Font Generator.exe</em> in the
@@ -2609,7 +2627,7 @@ Def.BitmapText{
 		Returns whether the spline is currently dirty.
 	</Function>
 	<Function name='destroy' return='' arguments=''>
-		Destroys the spline, freeing the memory allocated for it.  This can only be called on splines created with create_spline().
+		Destroys the spline, freeing the memory allocated for it.  This can only be called on splines created with <Link class='GLOBAL' function='create_spline'>create_spline()</Link>.
 	</Function>
 </Class>
 <Class name='DeviceList' grouping='Actor'>
@@ -3532,20 +3550,23 @@ end
 	<Function name='ChangeSort' return='bool' arguments='SortOrder so'>
 		Changes the sort order of the wheel.  Returns <code>true</code> if the order was changed.
 	</Function>
+	<Function name='GetCurrentSections' return='{string}' arguments=''>
+		Returns a string array of the currently displayed sections in the MusicWheel.
+	</Function>
 	<Function name='GetSelectedSection' return='string' arguments=''>
 		Returns the name of the currently selected section.
 	</Function>
 	<Function name='IsRouletting' return='bool' arguments=''>
 		Returns <code>true</code> if the MusicWheel is currently handling Roulette selection.
 	</Function>
-	<Function name='SelectSong' return='bool' arguments='Song sSong'>
+	<Function name='Move' return='void' arguments='int n'>
-		Selects a song. Returns <code>false</code> on failure.
+		Moves the wheel by <code>n</code>.
 	</Function>
 	<Function name='SelectCourse' return='bool' arguments='Course cCourse'>
 		Selects a course. Returns <code>false</code> on failure.
 	</Function>
-	<Function name='GetCurrentSections' return='{string}' arguments=''>
+	<Function name='SelectSong' return='bool' arguments='Song sSong'>
-		Returns a string array of the currently displayed sections in the MusicWheel.
+		Selects a song. Returns <code>false</code> on failure.
 	</Function>
 </Class>
 <Class name='NetworkManager'>
@@ -4684,10 +4705,11 @@ prev_note_name, succeeded = options:NoteSkin("cel")
 		Returns the profile for player <code>pn</code>.
 	</Function>
 	<Function name='GetProfileDir' return='string' arguments='ProfileSlot slot'>
-		Returns the profile directory of the specified <code>ProfileSlot</code>.
+		Returns the profile directory for the provided <Link class="ENUM" function="ProfileSlot">ProfileSlot</Link>, formatted like <code>/Save/LocalProfiles/00000001/</code>.<br />
+		Returns an empty string if the provided <Link class="ENUM" function="ProfileSlot">ProfileSlot</Link> does not have a <Link class="Profile" /> loaded.
 	</Function>
 	<Function name='GetSongNumTimesPlayed' return='int' arguments='Song s, ProfileSlot ps'>
-		Returns the number of times Song s has been played with the specified ProfileSlot.
+		Returns the number of times Song <code>s</code> has been played with the specified <Link class="ENUM" function="ProfileSlot">ProfileSlot</Link>.
 	</Function>
 	<Function name='GetStatsPrefix' return='string' arguments=''>
 		Returns the current stats prefix.
@@ -6015,6 +6037,9 @@ local spr = Def.Sprite{
 	<Function name='GetCurStageStats' return='StageStats' arguments=''>
 		Returns the current StageStats.
 	</Function>
+	<Function name='GetFinalEvalStageStats' return='Grade' arguments='PlayerNumber pn'>
+		Returns player <code>pn</code>'s final grade.
+	</Function>
 	<Function name='GetFinalGrade' return='Grade' arguments='PlayerNumber pn'>
 		Returns player <code>pn</code>'s final grade.
 	</Function>