• Stars
    star
    13
  • Rank 1,507,721 (Top 30 %)
  • Language
    Lua
  • License
    MIT License
  • Created about 9 years ago
  • Updated almost 9 years ago

Reviews

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.

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

License

MIT, see LICENSE for details.