AP_Scripting: docs: allow overload of manual bindings to allow documentation of optional arguments

Tools/scripts/run_lua_language_check.py

@@ -129,9 +129,9 @@ if __name__ == '__main__':
     p = subprocess.Popen(command, shell=True, text=True, stdout=subprocess.PIPE)
     result = []
     while p.poll() is None:
-        l = p.stdout.readline()
-        result.append(l)
-        print(l, end="")
+        line = p.stdout.readline()
+        result.append(line)
+        print(line, end="")
 
     # Make sure we checked at least one file
     file_count_re = re.compile(r"^>*=* \d+/(\d+)")

libraries/AP_Scripting/docs/docs.lua

@@ -69,14 +69,21 @@ function print(text) end
 -- data flash logging to SD card
 logger = {}
 
--- write value to data flash log with given types and names, optional units and multipliers, timestamp will be automatically added
+-- write value to data flash log with given types and names with units and multipliers, timestamp will be automatically added
 ---@param name string -- up to 4 characters
 ---@param labels string -- comma separated value labels, up to 58 characters
 ---@param format string -- type format string, see https://github.com/ArduPilot/ardupilot/blob/master/libraries/AP_Logger/README.md
----@param units? string -- optional units string
----@param multipliers? string -- optional multipliers string
----@param data1 integer|number|uint32_t_ud|string -- data to be logged, type to match format string
-function logger:write(name, labels, format, units, multipliers, data1, ...) end
+---@param units string -- units string
+---@param multipliers string -- multipliers string
+---@param ... integer|number|uint32_t_ud|string -- data to be logged, type to match format string
+function logger:write(name, labels, format, units, multipliers, ...) end
+
+-- write value to data flash log with given types and names, timestamp will be automatically added
+---@param name string -- up to 4 characters
+---@param labels string -- comma separated value labels, up to 58 characters
+---@param format string -- type format string, see https://github.com/ArduPilot/ardupilot/blob/master/libraries/AP_Logger/README.md
+---@param ... integer|number|uint32_t_ud|string -- data to be logged, type to match format string
+function logger:write(name, labels, format, ...) end
 
 -- log a files content to onboard log
 ---@param filename string -- file name

libraries/AP_Scripting/generator/description/bindings.desc

@@ -843,7 +843,7 @@ singleton AP_EFI method get_state void EFI_State'Ref
 include AP_Logger/AP_Logger.h
 singleton AP_Logger depends HAL_LOGGING_ENABLED
 singleton AP_Logger rename logger
-singleton AP_Logger manual write AP_Logger_Write 7 0
+singleton AP_Logger manual write AP_Logger_Write 6 0
 singleton AP_Logger method log_file_content void string
 singleton AP_Logger method log_file_content depends HAL_LOGGER_FILE_CONTENTS_ENABLED
 

libraries/AP_Scripting/tests/docs_check.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python3
+
 '''
 Reads two lua docs files and checks for differences
 
@@ -16,6 +18,14 @@ class method(object):
         self.full_line = full_line
         self.returns = returns
         self.params = params
+        self.manual = False
+        for i in range(len(self.returns)):
+            if self.returns[i][0] == 'UNKNOWN':
+                self.manual  = True
+
+        for i in range(len(self.params)):
+            if self.params[i][0] == 'UNKNOWN':
+                self.manual  = True
 
     def __str__(self):
         ret_str = "%s\n" % (self.full_line)
@@ -74,6 +84,11 @@ class method(object):
     def __eq__(self, other):
         return (self.global_name == other.global_name) and (self.local_name == other.local_name) and (self.num_args == other.num_args)
 
+    def is_overload(self, other):
+        # Allow manual bindings to have fewer arguments
+        # this allows multiple function definitions with different params
+        return other.manual and (self.global_name == other.global_name) and (self.local_name == other.local_name) and (self.num_args < other.num_args)
+
 def get_return_type(line):
     try:
         match = re.findall("^---@return (\w+(\|(\w+))*)", line)
@@ -85,7 +100,7 @@ def get_return_type(line):
 
 def get_param_type(line):
     try:
-        match = re.findall("^---@param \w+\?? (\w+(\|(\w+))*)", line)
+        match = re.findall("^---@param (?:\w+\??|...) (\w+(\|(\w+))*)", line)
         all_types = match[0][0]
         return all_types.split("|")
 
@@ -136,9 +151,6 @@ def parse_file(file_name):
                 num_args = 0
             else:
                 num_args = args.count(",") + 1
-                # ... shows up in arg list but not @param, add a unknown param
-                if args.endswith("..."):
-                    params.append(["UNKNOWN"])
 
             if num_args != len(params):
                 raise Exception("Missing \"---@param\" for function: %s", line)
@@ -194,7 +206,7 @@ def compare(expected_file_name, got_file_name):
     for got in got_methods:
         found = False
         for meth in expected_methods:
-            if got == meth:
+            if (got == meth) or got.is_overload(meth):
                 found = True
                 break
         if not found: