From 0649d1c77e597f663225f17c0b0405b14213c52c Mon Sep 17 00:00:00 2001 From: adelikat Date: Tue, 3 Jun 2014 02:19:13 +0000 Subject: [PATCH] Lua - add some more documentation, add a method that generates tasvideos wiki markup of the documentation and outputs to a file (method not wired to anything, there to save me tons of time when releasing) --- .../lua/EmuLuaLibrary.Bit.cs | 3 ++ .../lua/EmuLuaLibrary.Events.cs | 3 ++ .../lua/EmuLuaLibrary.MainMemory.cs | 3 ++ .../lua/EmuLuaLibrary.Memory.cs | 3 ++ .../lua/EmuLuaLibrary.NES.cs | 4 +- .../lua/EmuLuaLibrary.SNES.cs | 3 ++ .../lua/EmuLuaLibrary.String.cs | 2 + BizHawk.Client.Common/lua/LuaDocumentation.cs | 42 +++++++++++++++++++ BizHawk.Client.Common/lua/LuaLibraryBase.cs | 8 +++- .../Lua/Libraries/EmuLuaLibrary.Client.cs | 2 + .../Lua/Libraries/EmuLuaLibrary.Forms.cs | 2 + .../Lua/Libraries/EmuLuaLibrary.Input.cs | 2 +- .../tools/Lua/Libraries/EmuLuaLibrary.cs | 2 +- BizHawk.Common/ReflectionUtil.cs | 14 +++++++ 14 files changed, 88 insertions(+), 5 deletions(-) diff --git a/BizHawk.Client.Common/lua/EmuLuaLibrary.Bit.cs b/BizHawk.Client.Common/lua/EmuLuaLibrary.Bit.cs index 50c3752695..ec3e60ff51 100644 --- a/BizHawk.Client.Common/lua/EmuLuaLibrary.Bit.cs +++ b/BizHawk.Client.Common/lua/EmuLuaLibrary.Bit.cs @@ -1,8 +1,11 @@ using System; +using System.ComponentModel; + using LuaInterface; namespace BizHawk.Client.Common { + [Description("A library for performing standard bitwise operations.")] public sealed class BitLuaLibrary : LuaLibraryBase { public BitLuaLibrary(Lua lua) diff --git a/BizHawk.Client.Common/lua/EmuLuaLibrary.Events.cs b/BizHawk.Client.Common/lua/EmuLuaLibrary.Events.cs index 247f72b3ec..ced5e63d01 100644 --- a/BizHawk.Client.Common/lua/EmuLuaLibrary.Events.cs +++ b/BizHawk.Client.Common/lua/EmuLuaLibrary.Events.cs @@ -1,10 +1,13 @@ using System; using System.Linq; +using System.ComponentModel; using LuaInterface; + namespace BizHawk.Client.Common { + [Description("A library for registering lua functions to emulator events.\n All events support multiple registered methods.\nAll registered event methods can be named and return a Guid when registered")] public sealed class EventLuaLibrary : LuaLibraryBase { private readonly LuaFunctionList _luaFunctions = new LuaFunctionList(); diff --git a/BizHawk.Client.Common/lua/EmuLuaLibrary.MainMemory.cs b/BizHawk.Client.Common/lua/EmuLuaLibrary.MainMemory.cs index b39f49e7c7..fa71790e58 100644 --- a/BizHawk.Client.Common/lua/EmuLuaLibrary.MainMemory.cs +++ b/BizHawk.Client.Common/lua/EmuLuaLibrary.MainMemory.cs @@ -1,9 +1,12 @@ using System; +using System.ComponentModel; + using LuaInterface; using BizHawk.Emulation.Common; namespace BizHawk.Client.Common { + [Description("Main memory library reads and writes from the Main memory domain (the default memory domain set by any given core)")] public sealed class MainMemoryLuaLibrary : LuaMemoryBase { public MainMemoryLuaLibrary(Lua lua) diff --git a/BizHawk.Client.Common/lua/EmuLuaLibrary.Memory.cs b/BizHawk.Client.Common/lua/EmuLuaLibrary.Memory.cs index 0ca02b37f9..4d1dda5112 100644 --- a/BizHawk.Client.Common/lua/EmuLuaLibrary.Memory.cs +++ b/BizHawk.Client.Common/lua/EmuLuaLibrary.Memory.cs @@ -1,9 +1,12 @@ using System; +using System.ComponentModel; + using LuaInterface; using BizHawk.Emulation.Common; namespace BizHawk.Client.Common { + [Description("These functions behavior identically to the mainmemory functions but the user can set the memory domain to read and write from. The default domain is main memory. Use getcurrentmemorydomain(), and setcurrentmemorydomain() to control which domain is used. Each core has its own set of valid memory domains. Use getmemorydomainlist() to get a list of memory domains for the current core loaded.")] public sealed class MemoryLuaLibrary : LuaMemoryBase { private int _currentMemoryDomain; // Main memory by default probably (index 0 is currently always main memory but may never be) diff --git a/BizHawk.Client.Common/lua/EmuLuaLibrary.NES.cs b/BizHawk.Client.Common/lua/EmuLuaLibrary.NES.cs index 85c7b70370..deeb363653 100644 --- a/BizHawk.Client.Common/lua/EmuLuaLibrary.NES.cs +++ b/BizHawk.Client.Common/lua/EmuLuaLibrary.NES.cs @@ -1,13 +1,15 @@ using System; +using System.ComponentModel; using System.Linq; using LuaInterface; - using BizHawk.Emulation.Cores.Nintendo.NES; using BizHawk.Emulation.Cores.Consoles.Nintendo.QuickNES; + namespace BizHawk.Client.Common { + [Description("Functions related specifically to Nes Cores")] public sealed class NesLuaLibrary : LuaLibraryBase { // TODO: diff --git a/BizHawk.Client.Common/lua/EmuLuaLibrary.SNES.cs b/BizHawk.Client.Common/lua/EmuLuaLibrary.SNES.cs index ac52a50964..9f8b8205f2 100644 --- a/BizHawk.Client.Common/lua/EmuLuaLibrary.SNES.cs +++ b/BizHawk.Client.Common/lua/EmuLuaLibrary.SNES.cs @@ -1,9 +1,12 @@ using System; +using System.ComponentModel; + using LuaInterface; using BizHawk.Emulation.Cores.Nintendo.SNES; namespace BizHawk.Client.Common { + [Description("Functions specific to SNESHawk (functions may not run when an SNES game is not loaded)")] public sealed class SnesLuaLibrary : LuaLibraryBase { public SnesLuaLibrary(Lua lua) diff --git a/BizHawk.Client.Common/lua/EmuLuaLibrary.String.cs b/BizHawk.Client.Common/lua/EmuLuaLibrary.String.cs index 5cef5b4c7d..94590d69ab 100644 --- a/BizHawk.Client.Common/lua/EmuLuaLibrary.String.cs +++ b/BizHawk.Client.Common/lua/EmuLuaLibrary.String.cs @@ -1,10 +1,12 @@ using System; +using System.ComponentModel; using System.Linq; using LuaInterface; namespace BizHawk.Client.Common { + [Description("A library exposing standard .NET string methods")] public sealed class StringLuaLibrary : LuaLibraryBase { public override string Name { get { return "bizstring"; } } diff --git a/BizHawk.Client.Common/lua/LuaDocumentation.cs b/BizHawk.Client.Common/lua/LuaDocumentation.cs index aef22fe834..e93662b89d 100644 --- a/BizHawk.Client.Common/lua/LuaDocumentation.cs +++ b/BizHawk.Client.Common/lua/LuaDocumentation.cs @@ -1,4 +1,5 @@ using System.Collections.Generic; +using System.IO; using System.Linq; using System.Reflection; using System.Text; @@ -9,6 +10,46 @@ namespace BizHawk.Client.Common { public LuaDocumentation() :base() { } + + public void ToTASVideosWikiMarkup() + { + var sb = new StringBuilder(); + + sb + .AppendLine("[module:ListParents]") + .AppendLine() + .AppendLine("This page documents the the behavior and parameters of Lua functions available for the [BizHawk] emulator.") + .AppendLine() + .AppendLine(); + + foreach (var library in this.Select(x => new { Name = x.Library, Description = x.LibraryDescription }).Distinct()) + { + sb + .AppendFormat("%%TAB {0}%%", library.Name) + .AppendLine() + .AppendLine(); + if (!string.IsNullOrWhiteSpace(library.Description)) + { + sb + .Append(library.Description) + .AppendLine() + .AppendLine(); + } + + foreach (var func in this.Where(x => x.Library == library.Name)) + { + sb + .AppendFormat("__{0}.{1}__%%%", func.Library, func.Name) + .AppendLine().AppendLine() + .AppendFormat("* {0} {1}.{2}{3}", func.ReturnType, func.Library, func.Name, func.ParameterList) + .AppendLine().AppendLine() + .AppendFormat("* {0}", func.Description) + .AppendLine().AppendLine(); + } + } + + File.WriteAllText(Path.Combine(PathManager.GetExeDirectoryAbsolute(), "LuaDocumentationWiki.txt"), sb.ToString()); + } } public class LibraryFunction @@ -37,6 +78,7 @@ namespace BizHawk.Client.Common public List Parameters { get; set; } public string Description { get; set; } + public string LibraryDescription { get; set; } public string ParameterList { diff --git a/BizHawk.Client.Common/lua/LuaLibraryBase.cs b/BizHawk.Client.Common/lua/LuaLibraryBase.cs index a998265682..cee27a0452 100644 --- a/BizHawk.Client.Common/lua/LuaLibraryBase.cs +++ b/BizHawk.Client.Common/lua/LuaLibraryBase.cs @@ -2,6 +2,7 @@ using System.Linq; using LuaInterface; +using BizHawk.Common.ReflectionExtensions; namespace BizHawk.Client.Common { @@ -30,7 +31,7 @@ namespace BizHawk.Client.Common } } - public virtual void LuaRegister(LuaDocumentation docs = null) + public virtual void LuaRegister(Type callingLibrary, LuaDocumentation docs = null) { Lua.NewTable(Name); @@ -48,7 +49,10 @@ namespace BizHawk.Client.Common if (docs != null) { - docs.Add(new LibraryFunction(Name, luaMethodAttr.Name, method, luaMethodAttr.Description)); + docs.Add(new LibraryFunction(Name, luaMethodAttr.Name, method, luaMethodAttr.Description) + { + LibraryDescription = callingLibrary.Description() + }); } } } diff --git a/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Client.cs b/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Client.cs index 5a2397ceb4..86a4c6c09b 100644 --- a/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Client.cs +++ b/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Client.cs @@ -1,11 +1,13 @@ using System; using System.Collections.Generic; +using System.ComponentModel; using LuaInterface; using BizHawk.Client.Common; namespace BizHawk.Client.EmuHawk { + [Description("A library for manipulating the EmuHawk client UI")] public sealed class EmuHawkLuaLibrary : LuaLibraryBase { private readonly Dictionary _filterMappings = new Dictionary diff --git a/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Forms.cs b/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Forms.cs index 5d5355d00d..3823eed75e 100644 --- a/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Forms.cs +++ b/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Forms.cs @@ -1,5 +1,6 @@ using System; using System.Collections.Generic; +using System.ComponentModel; using System.Drawing; using System.Linq; using System.Windows.Forms; @@ -9,6 +10,7 @@ using LuaInterface; namespace BizHawk.Client.EmuHawk { + [Description("A library for creating and managing custom dialogs")] public sealed class FormsLuaLibrary : LuaLibraryBase { public FormsLuaLibrary(Lua lua) diff --git a/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Input.cs b/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Input.cs index 0773d787fb..ae4de963d8 100644 --- a/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Input.cs +++ b/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Input.cs @@ -19,7 +19,7 @@ namespace BizHawk.Client.EmuHawk [LuaMethodAttributes( "get", - "Returns a lua table of all the buttons the user is currently pressing on their keyboard and gamepads" + "Returns a lua table of all the buttons the user is currently pressing on their keyboard and gamepads\nAll buttons that are pressed have their key values set to true; all others remain null.\nAll key names use the names from http://slimdx.mdxinfo.com/latestdocs/Help/Html/T_SlimDX_DirectInput_Key.htm and are case-sensitive." )] public LuaTable Get() { diff --git a/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.cs b/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.cs index 277054280c..9d9035b542 100644 --- a/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.cs +++ b/BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.cs @@ -68,7 +68,7 @@ namespace BizHawk.Client.EmuHawk foreach (var lib in libs) { var instance = (LuaLibraryBase)Activator.CreateInstance(lib, _lua); - instance.LuaRegister(Docs); + instance.LuaRegister(lib, Docs); Libraries.Add(lib, instance); } diff --git a/BizHawk.Common/ReflectionUtil.cs b/BizHawk.Common/ReflectionUtil.cs index 88f3521f41..947b87b950 100644 --- a/BizHawk.Common/ReflectionUtil.cs +++ b/BizHawk.Common/ReflectionUtil.cs @@ -1,5 +1,6 @@ using System; using System.Collections.Generic; +using System.ComponentModel; using System.Linq; using System.Reflection; using System.Text; @@ -11,6 +12,19 @@ namespace BizHawk.Common.ReflectionExtensions /// public static class ReflectionUtil { + public static string Description(this Type type) + { + var descriptions = (DescriptionAttribute[]) + type.GetCustomAttributes(typeof(DescriptionAttribute), false); + + if (descriptions.Length == 0) + { + return string.Empty; + } + + return descriptions[0].Description; + } + /// /// Takes an object and determines if it has methodName as a public method ///