From bbb88f555e509a43ea303e0a0d772835f7da5e4d Mon Sep 17 00:00:00 2001 From: Andreas Date: Sat, 27 Apr 2024 18:50:10 +0200 Subject: [PATCH] Copy comment blocks. --- .gitignore | 2 + Readme.org | 2 +- example/Makefile | 2 + rockspecs/luals2dox-0.3-1.rockspec | 48 ++++++++++++ src/luals2dox/core.lua | 119 +++++++++++------------------ test/.gitignore | 1 + test/class/class-access-02.cpp | 6 ++ test/func/func-01.cpp | 1 + test/func/func-args-01.cpp | 1 + test/func/func-args-02.cpp | 1 + test/func/func-async-01.cpp | 1 + test/func/func-depr-01.cpp | 1 + test/func/func-rets-01.cpp | 1 + test/generic/generic-01.cpp | 1 + test/generic/generic-02.cpp | 5 ++ test/misc/m01.cpp | 1 + test/misc/m02.cpp | 2 + test/misc/m03.cpp | 1 - test/var/arr-01.cpp | 1 + test/var/arr-02.cpp | 1 + test/var/dict-01.cpp | 5 ++ test/var/dict-02.cpp | 5 ++ test/var/var-01.cpp | 1 + test/var/var-02.cpp | 1 + test/var/var-03.cpp | 1 + test/var/var-04.cpp | 1 + test/var/var-05.cpp | 1 + 27 files changed, 136 insertions(+), 77 deletions(-) create mode 100644 rockspecs/luals2dox-0.3-1.rockspec diff --git a/.gitignore b/.gitignore index a3d6a53..8b0d243 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,5 @@ /html/ /css/ + +TODO.org diff --git a/Readme.org b/Readme.org index a8c7e81..0588889 100644 --- a/Readme.org +++ b/Readme.org @@ -23,7 +23,7 @@ Create a standard ~Doxyfile~ with #+begin_src shell $ doxygen -g #+end_src -and edit this file as described in Section [[sec:configuration][Configuration of Doxygen]]. +and edit this file as described in Section [[*Configuration in Doxygen]]. **** File ~doc.json~ diff --git a/example/Makefile b/example/Makefile index 72fd5c5..ba2d3c1 100644 --- a/example/Makefile +++ b/example/Makefile @@ -8,3 +8,5 @@ html/index.html: $(lua-files) clean: rm -rf html/ latex/ distclean: clean + +coverage: diff --git a/rockspecs/luals2dox-0.3-1.rockspec b/rockspecs/luals2dox-0.3-1.rockspec new file mode 100644 index 0000000..8c95e62 --- /dev/null +++ b/rockspecs/luals2dox-0.3-1.rockspec @@ -0,0 +1,48 @@ +---@diagnostic disable: lowercase-global + +rockspec_format = '3.0' + +package = 'luals2dox' +version = '0.3-1' +source = { + url = 'git+https://github.com/AndreasMatthias/Luals2dox.git', + tag = 'v0.3-1' +} + +description = { + summary = 'Doxygen filter for Lua files.', + detailed = [[ + Luals2dox is an input filter for Doxygen that filters Lua files. + Lua files shall be annotated for use with LuaLS, the Lua Language Server, + that is a necessary requirement for Luals2dox. + ]], + labels ={'doxygen', 'documentation'}, + homepage = 'https://github.com/AndreasMatthias/Luals2dox', + license = 'GPLv3' +} + +dependencies = { + 'lpeg', + 'argparse', + 'lua-cjson', + 'penlight', + 'f-strings', +} + +build = { + type = 'builtin', + modules = { + ['luals2dox.init'] = 'src/luals2dox/init.lua', + ['luals2dox.core'] = 'src/luals2dox/core.lua', + ['luals2dox.args'] = 'src/luals2dox/args.lua', + }, + install = { + bin = { + ['luals2dox'] = 'src/l2d.lua' + } + }, +} + +-- Local Variables: +-- mode: lua +-- End: diff --git a/src/luals2dox/core.lua b/src/luals2dox/core.lua index aa0d481..799c002 100644 --- a/src/luals2dox/core.lua +++ b/src/luals2dox/core.lua @@ -160,11 +160,11 @@ function Doxy:init() return end if self:getOS() == 'Windows' then - self.file_scheme = '^file:///' - self.dev_null = 'null' + self.file_scheme = '^file:///' --- File scheme + self.device_null = 'null' --- Device null else self.file_scheme = '^file://' - self.dev_null = '/dev/null' + self.device_null = '/dev/null' end self:set_lua_file() self:update_json() @@ -204,7 +204,7 @@ function Doxy:set_lua_file() end ----Convert first character of to lowercase. +---Convert first character of `file` to lowercase. --- ---The file name must be an absolute path. ---In Windows the first character is the drive letter. @@ -274,7 +274,7 @@ function Doxy:update_json() local ok, state, errno = os.execute(string.format('%s --doc_update > %s', self.args.lua_language_server, - self.dev_null)) + self.device_null)) if not ok then os.rename('doc.json', self.json_file) self.arg_parser:error(string.format( @@ -333,7 +333,7 @@ function Doxy:render_file() if self.args.all_files then content = '/// @file\n\n' end - content = content .. self:copy_doxy_commands() + content = content .. self:copy_comment_blocks() for _, section in ipairs(self.doc_json) do content = content .. self:render_section(section) end @@ -846,83 +846,52 @@ function Doxy:render_variable(section, name) end ----Copy commands (chunks) directly for lua file. ---- ----This is for doxygen commands (markups) that are not included in the json file, ----but copied directly from the lua file. ----@return string -function Doxy:copy_doxy_commands() - local fd = assert(io.open(self.lua_file, 'r')) - local content = '' - for _, cmd in ipairs({'@file', '@defgroup', '@addtogroup', '@mainpage'}) do - content = content .. self:copy_doxy_command(fd, cmd) - end - fd:close() - return content -end - - ----Copy doxygen command from lua file. ----@param fd file* # File descriptor. ----@param command string # Doxygen command. ----@return string -function Doxy:copy_doxy_command(fd, command) - local content = '' - local text - local continue = false - fd:seek('set') - for line in fd:lines() do - text, continue = self:copy_doxy_command_2(line, continue, command) - content = content .. text - end - if content ~= '' then - content = content .. '~~~~~~\n' - end - return trim(content) -end - - --- Captures comment without comment sign "`---`". local comment_pattern = ( ws * lpeg.P('---') * ws * lpeg.C(lpeg.P(1) ^ 0)) ----Helper function for copy_doxy_command_defgroup(). ----@return string ----@return boolean -function Doxy:copy_doxy_command_2(line, continue, command) - if not continue then - local command_pattern = self:make_pattern(command) - local capture = command_pattern:match(line) - if capture then - local content = f '/// {command}{capture}\n' - return content, true - else - return '', false - end - else - local capture = comment_pattern:match(line) - if capture == '' then - capture = '~~~~~~' - end - if capture then - local content = f '/// {capture}\n' - return content, true - else - return '', false +---Copy comment blocks. +--- +---Comment blocks are one or more comment lines that start and +---end with a blank line. For the very first comment block of +---a file the starting blank line is optional. +function Doxy:copy_comment_blocks() + local function is_blank(line) + return line:match('^%s*$') + end + local fd = assert(io.open(self.lua_file, 'r')) + local content = '' + local block = '' + local block_started = true + for line in fd:lines() do + if block_started then + local comment = comment_pattern:match(line) + if comment then + ---comment line + if comment == '' then + block = block .. '/// ~~~~~~\n' + else + block = block .. f '/// {comment}\n' + end + elseif is_blank(line) then + ---blank line + if block ~= '' then + content = content .. block .. '~~~~~~\n' + end + block = '' + else + ---code line + block = '' + block_started = false + end + elseif is_blank(line) then + block_started = true end end -end - - ----Return lpeg pattern for doxygen command. ----@param command string # Doxygen command. ----@return Pattern -function Doxy:make_pattern(command) - return (ws * lpeg.P('---') * - ws * lpeg.P(command) * - (ws * lpeg.C(lpeg.P(1) ^ 0)) ^ -1) + content = content .. block -- If EOF follows comment block immediately. + return content end diff --git a/test/.gitignore b/test/.gitignore index 4e5a731..dbe5a59 100644 --- a/test/.gitignore +++ b/test/.gitignore @@ -6,3 +6,4 @@ /luacov.report.out /luacov.report.out.index /*.run +/var/tmp_file.lua diff --git a/test/class/class-access-02.cpp b/test/class/class-access-02.cpp index d3baea6..3fc6827 100644 --- a/test/class/class-access-02.cpp +++ b/test/class/class-access-02.cpp @@ -1,3 +1,9 @@ +/// This is ClassB. +/// @class ClassB +/// @field private privateField integer This is a `private` field. +/// @field protected protectedField integer This is a `protected` field. +/// @field publicField integer This is a `public` field. + /// /// @class ClassB /// diff --git a/test/func/func-01.cpp b/test/func/func-01.cpp index 16b811d..d7dc6cf 100644 --- a/test/func/func-01.cpp +++ b/test/func/func-01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// @brief This is the short description. diff --git a/test/func/func-args-01.cpp b/test/func/func-args-01.cpp index 761d032..28e1c5b 100644 --- a/test/func/func-args-01.cpp +++ b/test/func/func-args-01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Global functions. diff --git a/test/func/func-args-02.cpp b/test/func/func-args-02.cpp index 8356ff5..863de14 100644 --- a/test/func/func-args-02.cpp +++ b/test/func/func-args-02.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Same function names as in `func-args-01.lua`. diff --git a/test/func/func-async-01.cpp b/test/func/func-async-01.cpp index cbe15a5..69db3c2 100644 --- a/test/func/func-async-01.cpp +++ b/test/func/func-async-01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Async functions. diff --git a/test/func/func-depr-01.cpp b/test/func/func-depr-01.cpp index 1f9ab7d..446e6f4 100644 --- a/test/func/func-depr-01.cpp +++ b/test/func/func-depr-01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Deprecated functions. diff --git a/test/func/func-rets-01.cpp b/test/func/func-rets-01.cpp index 332e676..600efb7 100644 --- a/test/func/func-rets-01.cpp +++ b/test/func/func-rets-01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Global functions. diff --git a/test/generic/generic-01.cpp b/test/generic/generic-01.cpp index bc0fdce..3de5e80 100644 --- a/test/generic/generic-01.cpp +++ b/test/generic/generic-01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// @brief diff --git a/test/generic/generic-02.cpp b/test/generic/generic-02.cpp index 8a6fafe..3ab3a65 100644 --- a/test/generic/generic-02.cpp +++ b/test/generic/generic-02.cpp @@ -1,5 +1,10 @@ +/// @diagnostic disable:lowercase-global /// @file +/// @class MyArray: { [integer]: T } + +/// @class MyDictionary: { [string]: T } + /// /// @class MyArray /// diff --git a/test/misc/m01.cpp b/test/misc/m01.cpp index 8b81db8..6a253a0 100644 --- a/test/misc/m01.cpp +++ b/test/misc/m01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// The following empty lines must not be removed! /// diff --git a/test/misc/m02.cpp b/test/misc/m02.cpp index 1233f5f..4181414 100644 --- a/test/misc/m02.cpp +++ b/test/misc/m02.cpp @@ -1,5 +1,7 @@ /// @file +/// @diagnostic disable lowercase:local + /// @brief /// @param cnt (integer) Counter. /// @returns (integer) diff --git a/test/misc/m03.cpp b/test/misc/m03.cpp index 478b43a..afe2e8e 100644 --- a/test/misc/m03.cpp +++ b/test/misc/m03.cpp @@ -18,4 +18,3 @@ /// reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla /// pariatur. Excepteur sint occaecat cupidatat non proident, sunt in /// culpa qui officia deserunt mollit anim id est laborum - diff --git a/test/var/arr-01.cpp b/test/var/arr-01.cpp index faa7b07..02b6669 100644 --- a/test/var/arr-01.cpp +++ b/test/var/arr-01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Array definitions. diff --git a/test/var/arr-02.cpp b/test/var/arr-02.cpp index 2a1a22d..a223468 100644 --- a/test/var/arr-02.cpp +++ b/test/var/arr-02.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Same variable names as in `arr-01.lua`. diff --git a/test/var/dict-01.cpp b/test/var/dict-01.cpp index c7a3f86..fc23c46 100644 --- a/test/var/dict-01.cpp +++ b/test/var/dict-01.cpp @@ -1,6 +1,11 @@ +/// @diagnostic disable:lowercase-global /// @file /// Dictionaries and tables. +/// The `table` type is identical to the `dictionary` type. +/// But the syntax to define `table` and `dictionary` in LuaLS +/// is different. Nevertheless the JSON output is the same. + /// @brief /// Dictionary: string -> integer. ❴ ❲string❳→ integer ❵ dict1; diff --git a/test/var/dict-02.cpp b/test/var/dict-02.cpp index 6d77fb0..5379482 100644 --- a/test/var/dict-02.cpp +++ b/test/var/dict-02.cpp @@ -1,6 +1,11 @@ +/// @diagnostic disable:lowercase-global /// @file /// Same variable names as in `dict-01.lua`. +/// The `table` type is identical to the `dictionary` type. +/// But the syntax to define `table` and `dictionary` in LuaLS +/// is different. Nevertheless the JSON output is the same. + /// @brief /// Dictionary: string -> integer. (Another one with the same name.) ❴ ❲string❳→ integer ❵ dict1; diff --git a/test/var/var-01.cpp b/test/var/var-01.cpp index 67376f3..b842e80 100644 --- a/test/var/var-01.cpp +++ b/test/var/var-01.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Global variables. diff --git a/test/var/var-02.cpp b/test/var/var-02.cpp index a00920c..3576c20 100644 --- a/test/var/var-02.cpp +++ b/test/var/var-02.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Same variable names as in `var-01.lua`. diff --git a/test/var/var-03.cpp b/test/var/var-03.cpp index 67376f3..b842e80 100644 --- a/test/var/var-03.cpp +++ b/test/var/var-03.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// Global variables. diff --git a/test/var/var-04.cpp b/test/var/var-04.cpp index e8159d9..f8570d4 100644 --- a/test/var/var-04.cpp +++ b/test/var/var-04.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// @brief diff --git a/test/var/var-05.cpp b/test/var/var-05.cpp index 67a86bd..78323fb 100644 --- a/test/var/var-05.cpp +++ b/test/var/var-05.cpp @@ -1,3 +1,4 @@ +/// @diagnostic disable:lowercase-global /// @file /// @brief