Generates a Markdown-formatted file by parsing an ESI Lua library.
How to use this extension?
Install and open Visual Studio Code. Press Ctrl+Shift+X or Cmd+Shift+X to open the Extensions pane.
Find and install the ESI to Markdown extension. Open any esi-libname.lua file in the Visual Studio Code editor.
Run the command 'ESI to Markdown', to open the Command Palette ether go to 'View -> Command Palette' in the menu or use the shortcut 'Ctrl+Shift+P'.
The newly created file is being placed in the same directory where the ESI-lib file is located.
Features
A new Markdown file is being created if an esi-libname.md file does't exist in the same directory.
The newly created file contains the following information:
Library module name
Library description
Library Dependencies
List of links for the Available functions in the library, only public functions
Documentation section with all public functions which include summary, description, parameters, usage and return sub-sections
Otherwise the tool will try to auto-merge the following areas in the existing Markdown file:
Dependencies section, if it doesn't exists, it will be inserted before the #Known Issues, #Legend or #Availabe functions
Function links in the Available functions section
Function signatures in the Documentation section
Supported tags/comments for public functions which are recognised by the tool
tag/comment
multiple
description
---
no
One-line short summary
--
yes
function's description
@param
yes
formal arguments of a function
@usage
yes
a Lua code snippet
@return
yes
returned values of a function
The comments block must start with a Summary comment, i.e. ---, in order to be recognized by the tool.
The above tags/comments are being processed, for now, only when a new file is being created and not in auto-merge mode.
Example of documenting a public function
-- private comments which are not going to the Markdown file
-- all the comments below the Summary (---) are being processed by the tool
--- FOO explodes strings.
-- It is a specialized joining operation on strings.
-- Use with wisdom!
-- @param str1 the first string
-- @param str2 the second string
-- @usage local r = lib:FOO("foo", "bar")
-- @usage return r
-- @return a string
function lib:FOO(str1, str2)
return str1 ..':'.. str2
end
