bjornbytes/docroc

Lua comments go in, documentation comes out.

docroc

Minimal library that parses formatted Lua comments and returns them as a table.

Usage

local docroc = require 'docroc'
local comments = docroc.process('file.lua')

comments is now a table of comment blocks in the file, each with a table of tags and a context key. The tags table is an array of the tags, but also groups the tags by type. The context key is a string containing the contents of the line after the comment block.

Notes on parsing:

• A comment block must start with three dashes. It ends on the next non-commented line.
• Tags are recognized as any sequence of letters that start with @, and continue until the next tag is encountered. The first tag is implicitly @description.

Example

Go from this:

--- Displays a friendly greeting.
-- @arg {string=} name - The person to greet.
-- @returns {number}
function greet(name)
  print('hi', name)
  return 3
end

to this:

{
  {
    context = 'function greet(name)',
    tags = {
      [1] = {
        tag = 'description',
        text = 'The person to greet.'
      },
      [2] = {
        tag = 'arg',
        text = '{string=} name - The person to greet',
        type = 'string',
        optional = true,
        name = 'name',
        description = 'The person to greet.'
      },
      [3] = {
        tag = 'returns',
        text = '{number}',
        type = 'number'
      },
      description = {...},
      arg = {...},
      returns = {...}
    }
  }
}

Processors

By default, when docroc finds a tag, it creates an entry with two keys: tag and text. tag contains the name of the tag and text contains the text after the tag. This behavior can be extended using the docroc.processors table:

docroc.processors.customTag = function(body)
  return {
    numberOfCharacters = #body,
    reversed = body:reverse()
  }
end

Now, if we process a file containing the following:

--- @customTag hello world
local test

We would get this:

{
  tag = 'customTag',
  text = 'hello world',
  numberOfCharacters = 11,
  reversed = 'dlrow olleh'
}

For convenience, docroc provides a default set of custom processors:

• @arg: Collects information on an argument to a function, including the type of the argument, whether or not it is optional, whether or not it has a default value, its name, and a description. The expected structure is @arg {<type>=<default>} <name> - <description>, all of which are optional. An equals sign after the type represents an optional argument.
• @returns: Similar to @arg, contains information on a return value of the function. It returns type and description keys, and expects a structure of @returns {<type>} <description>.

Related

• Locco
• LDoc

License

MIT, see LICENSE for details.