Copy comment blocks.

.gitignore

@@ -5,3 +5,5 @@
 
 /html/
 /css/
+
+TODO.org

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~
 

example/Makefile

@@ -8,3 +8,5 @@ html/index.html: $(lua-files)
 clean:
 	rm -rf html/ latex/
 distclean: clean
+
+coverage:

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:

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 <file> 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
 
 

test/.gitignore

@@ -6,3 +6,4 @@
 /luacov.report.out
 /luacov.report.out.index
 /*.run
+/var/tmp_file.lua

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
 ///

test/func/func-01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 
 /// @brief This is the short description.

test/func/func-args-01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Global functions.
 

test/func/func-args-02.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Same function names as in `func-args-01.lua`.
 

test/func/func-async-01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Async functions.
 

test/func/func-depr-01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Deprecated functions.
 

test/func/func-rets-01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Global functions.
 

test/generic/generic-01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 
 /// @brief

test/generic/generic-02.cpp

@@ -1,5 +1,10 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 
+/// @class MyArray<T>: { [integer]: T }
+
+/// @class MyDictionary<T>: { [string]: T }
+
 ///
 /// @class MyArray
 ///

test/misc/m01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// The following empty lines must not be removed!
 /// 

test/misc/m02.cpp

@@ -1,5 +1,7 @@
 /// @file
 
+/// @diagnostic disable lowercase:local
+
 /// @brief
 /// @param cnt (integer) Counter.
 /// @returns (integer) 

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
-

test/var/arr-01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Array definitions.
 

test/var/arr-02.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Same variable names as in `arr-01.lua`.
 

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;

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;

test/var/var-01.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Global variables.
 

test/var/var-02.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Same variable names as in `var-01.lua`.
 

test/var/var-03.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 /// Global variables.
 

test/var/var-04.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 
 /// @brief

test/var/var-05.cpp

@@ -1,3 +1,4 @@
+/// @diagnostic disable:lowercase-global
 /// @file
 
 /// @brief