Style guidelines, scopes, Logger and more

[lukrop]

Changes

All changes shouldn't affect anything that worked with MIST 4.1. There were no (external) API changes.

• Changed indention from mixed to spaces only. Spaces are always one column, tabs can vary in size depending on editor, configuration of editor and so on. Also removed trailing spaces and unnecessary newlines.
• Restructured the whole file using do ... end scopes to simulate single files. Using a editor capable of code folding it gets a LOT easier navigating through the huge file. Also this allows for local functions beeing local only to the parts of mist which need them.
• Made functions definitions consistent function a.b() ... end With this style of defining functions we'll never run in problems with recursive functions. See recursive local functions at http://www.lua.org/pil/6.2.html.
• Made function names consistent camelCase. Except all mist.flagFunc functions.
• Made variable names consistent camelCase.
• Where applicable, substituted table['field'] with table.field to save some brackets and quotes.
• Dedicated mist.init() function as central entry point. Initializing database, creating logger instance, adding event handlers and finally calling mist.main() for the first time.
• Implemented mist.Logger class for easy logging with some nice features. More info see below
• Modified mist.groupTableCheck 12f2a39
• Created LDoc for most of the functions. This isn't complete but a good amount of all the functions is documented using LDoc. This enables us to have the API documentation automatically generated from the source code. It supports markdown and a intuitive syntax for inline function and table documentation. The automatically generated output of the currently added LDoc can be seen here. The output could easily be themed (CSS) and probably be used in the awesome hoggit wiki.

mist.Logger

Using this logger you get log levels (no more inline checks, whether to log or not, cluttering your code anymore) and, where possible, calling function and line number. E.g.

-- create the logger with MIST tag and info log level
local myLog = mist.Logger:new("MIST", "info")
myLog:msg('MIST version $1.$2.$3 loaded', mist.majorVersion, mist.minorVersion, mist.build)

generates the following log entry in %HOMEPATH%\Saved Games\DCS<.openbeta>\Logs\dcs.log

06409.078 INFO    SCRIPTING: MIST|init|983: MIST version 4.1.61 loaded

MIST beeing the tag, init the name of the function in which myLog:msg was called. And 983 the line at which the log function was called.

The logger functions accept everything as parameter and try their best to put out a string representation of what you throw at them. In other words you can just myLog:info(myTable) and you'll get a single line serialization of the table.

Dumping big tables, returned by let's say mist.utils.serialize, often ended up with overflowing the env.info function. The logger automatically works around that by just splitting log messages longer than 4000 chars into multiple messages. You'll never loose those precious debug info again. 😉 See here for API documentation.

Ideas & suggestions

I'd suggest to drop the changes file and just commit changes to git with a descriptive commit message. Also I would recommend to remove the mist_version_number_here.lua file and rely on tags and releases alone, as it's already the case. This keeps the repository clean. Using a development branch is already a way of keeping WIP out of the master branch.

Some functions names seem unclear/misleading to me e.g. mist.goRoute, mist.groupToRandomZone, mist.groupRandomDistSelf. Maybe we could rename those functions to be more descriptive of what they are doing. I know there is already a really good documentation in PDF form and if one reads the description he knows what the function does. It's just an observation of mistakes I made while using MIST the first time in a script.

Many functions use a table of vars as parameters. This could make debugging harder and I don't see the benefit from it. I'd suggest to deprecate those. Function signature still there, calling the new function with vars unpacked and logging a warning message that this function is deprecated.