From 364419be81010d868db2d7dcbdd370b37b441c06 Mon Sep 17 00:00:00 2001 From: Iampete1 Date: Sun, 2 Jun 2024 21:25:48 +0200 Subject: [PATCH] AP_Scripting: docs: allow overload of manual bindings to allow documentation of optional arguments --- Tools/scripts/run_lua_language_check.py | 6 ++--- libraries/AP_Scripting/docs/docs.lua | 17 +++++++++----- .../generator/description/bindings.desc | 2 +- libraries/AP_Scripting/tests/docs_check.py | 22 ++++++++++++++----- 4 files changed, 33 insertions(+), 14 deletions(-) diff --git a/Tools/scripts/run_lua_language_check.py b/Tools/scripts/run_lua_language_check.py index 5d67e49205..7353f01637 100755 --- a/Tools/scripts/run_lua_language_check.py +++ b/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+)") diff --git a/libraries/AP_Scripting/docs/docs.lua b/libraries/AP_Scripting/docs/docs.lua index 4db54caa04..dc45ddd06e 100644 --- a/libraries/AP_Scripting/docs/docs.lua +++ b/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 diff --git a/libraries/AP_Scripting/generator/description/bindings.desc b/libraries/AP_Scripting/generator/description/bindings.desc index 0f3afd589a..d366774530 100644 --- a/libraries/AP_Scripting/generator/description/bindings.desc +++ b/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 diff --git a/libraries/AP_Scripting/tests/docs_check.py b/libraries/AP_Scripting/tests/docs_check.py index f2c6b120b3..455534e689 100644 --- a/libraries/AP_Scripting/tests/docs_check.py +++ b/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: