docroc

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

Usage

localdocroc=require'docroc'localcomments=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}functiongreet(name)
print('hi', name)
return3end

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 worldlocaltest

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.