LUA API documentation is lacking

[z64555]

Having FSO output the scripting.html is a novel idea to keep modders up to date on what functions they have access to, but to be honest the result is very user unfriendly and everything isn't documented adequately.

One particular example is that the numerous Enumerations at the bottom of the scripting.html have no information on what exactly they do, or for that matter suggest some of the precautions a modder has to take in order for them to work correctly. This let to issues such as #4108 to occur

[JohnAFernandez]

This is a good issue to fix before 24.2

[z64555]

• [ ] Should have description of what a hook does.
• [ ] Should have a hyperlink index/table of context for fast navigation.

• [ ] Should have a description of what conditions are, and which condition pertains to which part of the game.

• [ ] Should have a description of what a Conditional Hook: Action is

• [ ] Suggest "Overridable: Yes/No." This is a reference document. Complete sentances take up both screen space and time to read in order to convey the idea. Reference material is meant for fast lookup and data recovery, especially if it is used often. Keeping the text minimal decreases time spent used to convey the idea and reduces fatigue on the reader.

• [ ] Call signature e.g. 'Hook_name(argument)' is not clear in this example, so describing the "Hook Variable" just confuses. Variables, Conditions, Arguments are also unclear in both position and usage.

• [ ] This hook has several conditions that seem to be either sub-types or as alternative arguments for the hook. Without an call signature example, their purpose is confusing.

• [ ] Lua version should be at the top of the file
• [ ] Short description of where the libraries are from: Internal FSO code, linked external library, or internal LUA library?

• [ ] Recommend Short description of what Types are, and where they are from (FSO, library, etc.)

• [ ] Recommend short description of what Enumerations are, where they are from (FSO, library, etc.)

• [ ] Libraries section needs a header title. in their actual section

• [ ] Function descriptions within the LIbraries section do include a call signature of the respective function, but don't provide a concise description of the arguments. Recommend doxygen-style.

• [ ] Deprecation footnotes should be at the bottom, after the description of the function, its return values, side effects, etc.

• [ ] Bitops Arguments are nameless, which can be confusing to read.
• [ ] Optional additional arguments could be reduced down using ellipses. This'll probably need a manual override. Example formate: 'number AND(number n1, number n2, [number n3, ... , number n10])'

• [ ] Where are the valid keybindings? Provide a link or hint to where to find them.

• [ ] This provides a set of valid enumerations, but the position and type layout is sloppy. Recommend doxygen style.

• [ ] What is this value subfield? Is it the valid values for the argument, or the possible return values of the function?

• [ ] Table call signature is confusing
• [ ] Tables should be separated from functions with section titles

• [ ] "IMPORTANT" should be a separate field from Description

• [ ] Overloaded Call signature is awkward to read. Recommend making two entries. e.g. 'drawImage(string fileName...) drawImage(texture Texture, ...)'

• [ ] The heck is that first entry? What is its call signature?

• [ ] Overloaded arguments of varying types. Recommend call signature of each.

[z64555]

...Yeahhh there's a lot of work to be done. breaking this up into multiple pages is recommended, as it is quite a bit of information to scroll/search through.

[z64555]

• [ ] Object descriptions are lacking a header to seperate them from the API descriptions. Should have a short description explaining what objects are (they're data types that aggregate data, etc.)

• [ ] Enumerations have no description nor are they grouped according to use/definition