module docs

This module contains the runtime interface to Croc's built-in documentation system. It defines the decorator function which the compiler can translate doc comments into, as well as the actual documentation processing functions. It also contains a basic doc outputting scaffold, so that you can output documentation in a human-readable format without much extra work.

This is a decorator function used to attach documentation tables to objects. The compiler can attach calls to this decorator to declarations in your code automatically by extracting documentation comments and information about the declarations from the code.

Once the documentation table has been set for an object, you can retrieve it with docsOf, which can then be further processed and output in a human-readable form (for instance, by using the various doc output classes).

This function is also exported in the global namespace so that you can access it unqualified (that is, both _doc_ and docs._doc_ refer to this function).

Params:
val
is the decorated object and can be any reference type.
doctable
is a table, presumably one which matches the specifications for doc tables.
vararg
should all be integers and are used to extract the correct sub-table from the root documentation table (the doctable parameter). So, for instance, using "@_doc_(someTable, 0, 2)" on a declaration would mean that the table someTable.children[0].children[2] would be used as the documentation for the decorated declaration. If no variadic arguments are given, the table itself is set as the documentation table of the object.

Returns:

val as per the decorator protocol.

Throws:
TypeError
if any of the varargs are not ints, or if the value that will be set as the doctable for val is not a table.

global function docsOf(val)

This retrieves the documentation table, if any, associated with an object.

Params:
val
is the object whose docs are to be retrieved. Any type is allowed, but only reference types can have documentation tables associated with them.
Some program elements can't have their docs directly retrieved with this function. See also metamethodDocs and childDocs.

Returns:

the doc table for val if one has been set, or null if none has been set (or if val is a value type).

global function metamethodDocs(type: string, method: string)

This retrieves the documentation table, if any, associated with a metamethod in a global type metatable.

Normally, without access to the debug lib, Croc code can't actually get a direct reference to these methods (such as the format method of strings). This function lets you get docs for those methods without the debug lib.

Params:
type
is the name of the built-in type you want to get the method's docs from.
method
is the name of the method to get the docs of.

Returns:

the doc table for the given method if one has been set, or null if not.

Throws:
ValueError
if type does not name a valid built-in type, or if type has no metatable set for it.
FieldError
if there is no method named method in type's metatable.

global function childDocs(obj: class|namespace, child: string)

This retrieves the documentation table, if any, associated with a child element of a class or namespace.

Functions defined in classes and namespaces can have their docs accessed directly, but for other fields, you have to access their doc tables through their parents' children doctable member. This function automates that for you.

Params:
obj
is the class or namespace in which the field is defined.
child
is the name of the field whose docs you want to retrieve. Any field name is valid, not just non-functions.

Returns:

the doc table for the given field if one has been set, or null if not.

Throws:
ValueError
if obj has no child named child, or if obj has no doctable.

global function processComment(comment: string, doctable: table)

Low-level function which takes the raw text from a doc comment and a doctable (with no docs member) and parses the doc comment, adding the appropriate members to the given doctable.

This is actually the same function that the compiler itself calls to process doc comments. Note that the doctable that is to be passed to this function must be properly formed (with all the "standard" members, as well as any extra kind-specific members as defined in the doc comment spec), but there must be no "docs" members at all. The "docs" members, as well as members for other sections, will be filled in by this function.

Params:
comment
is the raw text of the doc comment.
doctable
is the doctable as explained above.

Returns:

the doctable parameter.

Throws:
SyntaxException
if parsing the comment failed. Note that in this case the doctable may be partially filled-in.

global function parseCommentText(comment: string)

Takes a string containing Croc doc comment markup, and parses it into a paragraph list.

This doesn't parse the whole text of a doc comment; rather it just parses one or more paragraphs of text. Section commands are not allowed to appear in the text. Span and text structure commands, however, are valid.

Params:
comment
is the raw markup to be parsed.

Returns:

an array which is a paragraph list as defined in the doc comment spec.

Throws:
SyntaxException
if parsing failed.

class DocVisitor

A class which defines a simple interface for visiting all the elements in a doctable. You can use this as a base class for your own visitors to do things like output docs in various formats.

By default this class doesn't do much, but it does remove some of the boilerplate involved in dispatching to the various methods. Some methods are unimplemented and must be defined in a derived class in order to work.

Note that there is another class, doctools.output.OutputDocVisitor, which implements this class's interface in a way that makes making document outputters easier.

function DocVisitor.visitItem(item: table)

Visits one program item's doctable. This dispatches based on item.kind to one of the six methods after this one.

Throws:
ValueError
if the given doctable has an invalid kind field.

function DocVisitor.visitModule(item: table) function DocVisitor.visitClass(item: table) function DocVisitor.visitNamespace(item: table) function DocVisitor.visitFunction(item: table) function DocVisitor.visitField(item: table) function DocVisitor.visitVariable(item: table)

These methods are called by visitItem. You must implement these methods yourself.

function DocVisitor.visitChildren(item: table)

A convenience method for doctables which have children (such as modules, classes, and namespaces). This just loops over the doctable's children field and calls visitItem on each one.

function DocVisitor.visitPlist(plist: array)

A convenience method for visiting a list of paragraphs (plist). This just loops over the plist and calls visitParagraph on each one.

function DocVisitor.visitParagraph(par: array)

Visits one paragraph of documentation. By default, just calls visitParagraphElements with par as the argument, but often you will want to do something at the beginning/end of a paragraph (such as insert indentation or newlines), so you can override this method to do so.

function DocVisitor.visitParagraphElements(elems: array)

Visits an array of paragraph elements. You can use this method to implement the text visitor methods which follow, and this method will dispatch to those visitor methods.

function DocVisitor.visitText(elem: string)

Visits a segment of plain text that appears in a paragraph. Must be overridden.

function DocVisitor.visitCode(language: string, contents: string)

Visits a code snippet. Must be overridden.

function DocVisitor.visitVerbatim(type: string, contents: string)

Visits a verbatim block. Must be overridden.

function DocVisitor.visitBlist(items: array)

Visits a bulleted list. Must be overridden.

function DocVisitor.visitNlist(type: string, items: array)

Visits a numbered list. Must be overridden.

function DocVisitor.visitDlist(items: array)

Visits a definition list. Must be overridden.

function DocVisitor.visitTable(rows: array)

Visits a table. Must be overridden.

function DocVisitor.visitBold(contents: array)

Visits an bold text span. Must be overridden.

function DocVisitor.visitEmphasis(contents: array)

Visits an emphasis text span. Must be overridden.

function DocVisitor.visitLink(link: string, contents: array)

Visits a link text span. Must be overridden.

function DocVisitor.visitStrikethrough(contents: array)

Visits an strikethrough text span. Must be overridden.

function DocVisitor.visitSubscript(contents: array)

Visits a subscript text span. Must be overridden.

function DocVisitor.visitSuperscript(contents: array)

Visits a superscript text span. Must be overridden.

function DocVisitor.visitMonospace(contents: array)

Visits a monospace text span. Must be overridden.

function DocVisitor.visitUnderline(contents: array)

Visits an underline text span. Must be overridden.

function DocVisitor.visitCustomSpan(type: string, contents: array)

Visits a custom text span. Must be overridden.

HTML and JavaScript source derived from

by Victor Nakoryakov; Page generated on 15 Nov 2014 10:28:14

val	is the decorated object and can be any reference type.
doctable	is a table, presumably one which matches the specifications for doc tables.
vararg	should all be integers and are used to extract the correct sub-table from the root documentation table (the `doctable` parameter). So, for instance, using "`@_doc_(someTable, 0, 2)`" on a declaration would mean that the table `someTable.children[0].children[2]` would be used as the documentation for the decorated declaration. If no variadic arguments are given, the table itself is set as the documentation table of the object.

type	is the name of the built-in type you want to get the method's docs from.
method	is the name of the method to get the docs of.

ValueError	if `type` does not name a valid built-in type, or if `type` has no metatable set for it.
FieldError	if there is no method named `method` in `type`'s metatable.

obj	is the class or namespace in which the field is defined.
child	is the name of the field whose docs you want to retrieve. Any field name is valid, not just non-functions.

comment	is the raw text of the doc comment.
doctable	is the doctable as explained above.