Add more documentation and corrections for gma.lua, gma.canbus, gma.n…

…etwork, gma.show and gma.show.getobj (#9) * 23w11a Added documentation and corrections for gma.lua, gma.canbus, gma.network, gma.show and gma.show.getobj * Update gma.canbus.lua Grammar, formatting, usage * Update gma.show.lua Updated formatting and usage * Update gma.show.getobj.lua Grammar, formatting, split Object Class Names to the wiki * Update gma.network.lua Grammar, formatting * Formatting fixes to get documenation to compile * Noted export location is for onPC --------- Co-authored-by: Eric Kincl <[email protected]>
Hobadee · Mar 18, 2023 · 121e4ce · 121e4ce
1 parent aaad7b1
commit 121e4ce
Show file tree

Hide file tree

Showing 5 changed files with 96 additions and 32 deletions.
diff --git a/gma.canbus.lua b/gma.canbus.lua
@@ -23,9 +23,11 @@ end
 -- Use it at your own risk.
 --
 --@tparam number encoder_number number to indicate the hardware encoder number. 0 is for encoder 1, 1 for encoder 2 and so on. I assume you can use 4 to emulate the screen encoder
---@tparam number steps use negative numbers to invert direction
---@tparam boolean pressed currently not really sure
+--@tparam number steps use negative numbers to invert direction. Set to `nil` if you want to emulate encoder press.
+--@tparam boolean pressed set to true/false to emulate key press/release. Set to `nil` to emulate rotation. (uisng encoder_number and steps)
 --@treturn boolean success returns true except when a wrong parameter count is given
+--@usage gma.canbus.encoder(0,-10,nil)
+--@usage gma.canbus.encoder(0,nil,true)
 function gma.canbus.encoder(encoder_number, steps, pressed)
 end
 

diff --git a/gma.lua b/gma.lua
@@ -53,28 +53,28 @@ end
 function gma.git_version()
 end
 
----Export a table as a file???
+---Export a table as a file. By default, MA uses XML as a file type.  Check @{gma.export_csv|export_csv()} and @{gma.export_json|export_json()} for other options.
 --
---@tparam string filename Filename to export to???
---@tparam table export_data Table object to export???
+--@tparam string filename Filename to export to. onPC exports to `\MA Lighting Technologies\grandma\gma2_V_<YourVersion>\temp`
+--@tparam table export_data Table object to export.
 function gma.export(filename,export_data)
 end
 
----Export a table as a CSV file?
+---Export a table as a CSV file
 --
---@tparam string filename Filename to export to???
---@tparam table export_data Table object to export???
+--@tparam string filename Filename to export to. onPC exports to `\MA Lighting Technologies\grandma\gma2_V_<YourVersion>\temp`
+--@tparam table export_data Table object to export
 function gma.export_csv(filename,export_data)
 end
 
----Export a table as a JSON file?
+---Export a table as a JSON file
 --
---@tparam string filename Filename to export to???
---@tparam table export_data Table object to export???
+--@tparam string filename Filename to export to. onPC exports to `\MA Lighting Technologies\grandma\gma2_V_<YourVersion>\temp`
+--@tparam table export_data Table object to export.
 function gma.export_json(filename,export_data)
 end
 
----Import a file as a table?
+---Import a file as a table. Can only import tables that are saved in XML Format?
 --
 --@tparam string filename Filename to import
 --@treturn table Imported data
@@ -96,9 +96,9 @@ end
 function gma.timer(name,dt,max_count,cleanup)
 end
 
----Returns the system time
+---Returns the system uptime
 --
---@treturn number Current LINUX time as returned by systemd???
+--@treturn number Current system uptime in seconds.
 function gma.gettime()
 end
 

diff --git a/gma.network.lua b/gma.network.lua
@@ -73,28 +73,83 @@ end
 function gma.network.getslot()
 end
 
-
----
+---Retrieves information about a host using the hosts IP address.
 --
---@tparam string ip IP Address
+-- Retrieved information:
+-- 
+-- * Host status (see @{gma.network.getstatus|network.getstatus()})
+-- * Primary ip address (see @{gma.network.getprimaryip|network.getprimaryip()}), 
+-- * Secondary ip address (see @{gma.network.getsecondaryip|network.getsecondaryip()})
+-- * Bits (64/32), hostname
+-- * Host network slot
+-- * Subnet mask
+-- * Whether invite is enaled
+-- * MAC address
+-- * Primary and secondary subnet mask
+-- * Software version
+-- * Software uptime
+-- * Software type (see @{gma.network.gethosttype|network.gethosttype()}) and subtype (see @{gma.network.gethostsubtype|network.gethostsubtype()})
+-- * Session number of the host.
+-- 
+--@tparam string ip IP Address of the host we want to get data from
 --@tparam ?table recycle ???
---@treturn table host_data ???
+--@treturn table host_data Table of host data.
 function gma.network.gethostdata(ip,recycle)
 end
 
----
+---Retrieves information about a host using the hosts slotID in MA_NET.
+-- 
+-- Retrieved information is:
+-- 
+-- * Host status (see @{gma.network.getstatus|network.getstatus()})
+-- * Primary ip address (see @{gma.network.getprimaryip|network.getprimaryip()})
+-- * Used paramters count, MA_NET slot ID,
+-- * DMX Count (?)
+-- * Secondary ip address (see @{gma.network.getsecondaryip|network.getsecondaryip()})
+-- * Bits (64/32)
+-- * Hostname
+-- * Host network slot
+-- * Subnet mask
+-- * Whether invite is enaled
+-- * MAC address
+-- * Primary and secondary subnet mask
+-- * Software version
+-- * Software uptime
+-- * Software type (see @{gma.network.gethosttype|network.gethosttype()}) and subtype (see @{gma.network.gethostsubtype|network.gethostsubtype()})
+-- * Session number of the host.
 --
---@tparam number slot???
+--@tparam number slot The MA_SLOT slot number for which we want to get information.
 --@tparam ?table recycle???
---@treturn table slot_data???
+--@treturn table a Table in which host data should be copied into.
 function gma.network.getmanetslot(slot,recycle)
 end
 
----
+---Returns performance statistics about a host using its MA_NET slot ID.
+--
+-- Collects the following performance data (values are in seconds?):
+-- 
+-- * RT_DecodeDMX
+-- * RT_DMXOutput
+-- * WaitForKeys
+-- * RT_HardwareEve
+-- * Wait25
+-- * RT_Jobques
+-- * RT_Effects
+-- * RT_Submaster
+-- * RT_LocalChanne
+-- * RT_BMP
+-- * RT_NormalChann
+-- * RT_PreviewChan
+-- * RT_Universes
+-- * RT_DMXEncode
+-- * RT_ChannelInfo
+-- * RT_FadersAndLe
+--
+-- Based of the permormance statistics names, the maximum length of a stat name is 14 characters.
 --
---@tparam number slot???
+--@tparam number slot The MA_SLOT slot number for which we want to get information.
 --@tparam ?table recycle???
---@treturn table performance_data???
+--@treturn table Performance data table.
 function gma.network.getperformance(slot,recycle)
 end
 

diff --git a/gma.show.getobj.lua b/gma.show.getobj.lua
@@ -22,8 +22,9 @@ end
 
 ---Get the class of the object.
 --
---@tparam number handle @{gma.show.getobj.handle|Handle} to get the class of.
---@treturn string Object's class name.
+--@tparam number handle @{gma.show.getobj.handle|Handle} to get the class of.  (See linked Wiki for a list)
+--@treturn string Object's class name. 
+--@see [Object class names](https://github.com/Hobadee/grandMA2_LUA_ldoc/wiki/Object-Class-Names)
 function gma.show.getobj.class(handle)
 end
 
@@ -44,7 +45,7 @@ end
 ---Get name of object.
 --
 --@tparam number handle @{gma.show.getobj.handle|Handle} to get name of.
---@treturn string Object name.
+--@treturn string Object name as displayed inside the MA GUI
 function gma.show.getobj.name(handle)
 end
 
@@ -54,7 +55,7 @@ end
 --
 --@tparam number handle @{gma.show.getobj.handle|Handle} to get label of.
 --@treturn ?string Object label.
---Returns nil if no label is set.
+--Returns `nil` if no label is set. Returns the same output as @{gma.show.getobj.name|Name} if the user set a label for the object.
 function gma.show.getobj.label(handle)
 end
 

diff --git a/gma.show.lua b/gma.show.lua
@@ -2,14 +2,20 @@
 --@module gma.show
 
 
----Gets the value of a DMX address?
+---Gets the value of a DMX address.
 --
---@tparam number dmx_addr DMX address
+-- May only output the value if MA has free parameters.
+--
+--@tparam number dmx_addr DMX address. Format as `<UNIVERSE>.<ADDRESS>`
 --@treturn number Value of DMX address
+--@usage gma.show.getdmx(1.1)
+--@usage gma.show.getdmx(3.54)
 function gma.show.getdmx(dmx_addr)
 end
 
----Gets the value of many DMX addresses???
+---Gets the value of multiple DMX addresses.
+--
+--May only output the value if MA has free parameters.
 --
 --@tparam table recycle ???
 --@tparam number dmx_addr ???
@@ -60,4 +66,4 @@ end
 --@tparam string varname varname to set
 --@tparam mixed value value to set to
 function gma.show.setvar(varname,value)
-end
+end