platoon.lua annotations and warning fixes [lua/platoon.lua]

[clyfordv]

Annotation and warning fixes for platoon.lua

files: lua/platoon.lua

focus:

• annotation fixes (optional params, corrects improper types, etc.)
• nil checks (mostly for GetPlatoonPosition) in logic where appropriate
• streamlines several GetPlatoonPosition calls into local variables
• converts several $type|false local variable declaration and returns into $type|nil

[relent0r]

Did testing of this in AI games and did not see any obvious errors except about that wall builder. It produces this, I did see you had another PR that was for the aiutilities but I haven't delved into it yet.

warning: Error running lua script: string expected but got userdata stack traceback: [C]: in function ParseEntityCategory' g:\code\fa\lua\ai\aiutilities.lua(1052): in functionGetLocationNeedingWalls' g:\code\fa\lua\platoon.lua(2274): in function <g:\code\fa\lua\platoon.lua:2192>

Though tbh its got a zero priority so is effectively disabled, you wouldn't know there was a problem unless you specifically enabled it.

[relent0r]

@clyfordv Can you add a snippets entry for this PR. It would be /changelog/snippets/ai.6083.md With just an entry of something like say - (#6083) annotations of platoon.lua and logic fixes