• Stars
  • Rank 1,563,796 (Top 32 %)
  • Language
  • License
    MIT License
  • Created almost 9 years ago
  • Updated over 8 years ago


There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Lua comments go in, documentation comes out.


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


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.


Go from this:

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

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 = {...}


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()

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



MIT, see LICENSE for details.