module doctools.output
This sub-module of the docs lib contains functionality for outputting docs in a human-readable form, as well as a small framework which makes it easier to output docs to new formats.
- class LinkResolver
This class defines a default behavior for mapping documentation links (made with the \link command) to the things they refer to. It uses a LinkTranslator which you define in order to turn the mapped links into outputtable link text.
For URIs (such as with \link{http://www.example.com}), no attempt is made to ensure the correctness or well- formedness of the link.
All other links are considered links to other documentable items. The way it does this is by taking a snapshot of the global namespace and all currenly-loaded modules. This means that any modules imported after instantiating this class are unknown to that instance, and links into them will not resolve. Most of the time this won't be a problem since you'll likely have imported them beforehand so that you can output their docs!
Once a link has been processed, it is then passed to one of the methods that its LinkTranslator instance defines. The results of those methods are returned from resolveLink.
- LinkResolver.this(trans)
Constructs a resolver with the given link translator.
The constructor takes a snapshot of the global namespace and all loaded modules, so if there are any modules that you want links to resolve to, you must have imported them before instantiating this class.
When you create a link resolver, any links will be evaluated within the global scope. You can change the scope in which links are resolved by using the enter/leaveItem/Module methods.
Params:
trans is the link translator object whose methods will be called by resolveLink.
- function LinkResolver.currentScope()
Returns a string saying what scope this resolver is currently operating in.
Returns:
one of "global" (the default), "module" (when you have entered a module), or "item" (when you have entered an item within a module).
- function LinkResolver.enterModule(name: string)
Switches from global scope to module scope, so that links will be resolved in the context of the given module.
Throws:
exceptions.StateError if the current scope is not global scope.
exceptions.ValueError if there is no module of the given name.
- function LinkResolver.enterItem(name: string)
Switches from module scope to item scope, so that links will be resolved in the context of the given item (class or namespace declaration).
Throws:
exceptions.StateError if the current scope is not module scope.
exceptions.ValueError if there is no item of the given name in the current module.
- function LinkResolver.leave()
Switches from the current scope to the owning scope.
Throws:
exceptions.StateError if the current scope is global scope.
- function LinkResolver.resolveLink(link: string)
Given a raw, unprocessed link, turns it into a link string suitable for output.
It does this by analyzing the link, determining whether it's a URI or a code link, ensuring it's a valid link if it's a code link, and then calling one of LinkTranslator's methods as appropriate to turn the raw link into something suitable for output. It does not process the outputs of those methods; whatever they return is what this method returns.
- class NullLinkResolver : LinkResolver
A link resolver that does absolutely nothing and resolves all links to whatever was passed in.
It never throws any errors or does anything. It's useful for when you don't want any link resolution behavior at all.
- class LinkTranslator
This class defines an interface for mapping links from their raw form to their outputtable form. Since the structure of the output docs is unknown to the library, how this translation happens is left up to the user.
You create a subclass of this class, override the appropriate methods, and then pass an instance of it to the constructor of LinkResolver.
- function LinkTranslator.translateLink(mod: string, item: string)
Given a module name and a sub-item name (which may or may not be dotted, since it might be something like a class field), translates them into a suitable link string.
This, and translateURI, are the only methods you have to override in a subclass.
Both the mod and item parameters may either be the empty string or a non-empty string, and the meanings of those combinations are as follows:
mod == "", item == "": the link points to the global namespace (i.e. the Croc baselib).
mod == "", item != "": the link points to the global named item.
mod != "", item == "": the link points to the module named mod.
mod != "", item != "": the link points to the item named item in the module named mod.
Params:
mod is the name of the module, as explained above.
item is the name of the item, as explained above.
Returns:
the link translated into a form that makes sense to whatever output format you're using.
- function LinkTranslator.translateURI(uri: string)
Given a URI, translates it into a suitable link string.
This, and translateLink, are the only methods you have to override in a subclass.
Params:
uri is the URI to translate.
Returns:
the link translated into a form that makes sense to whatever output format you're using.
- function LinkTranslator.invalidLink(link: string)
This method is called when the given link fails to resolve.
LinkResolver.resolveLink will call this method if it fails to find a valid target for the given link. This method can return a string which will then be returned by LinkResolver.resolveLink. By default, this method throws a exceptions.ValueError saying which link failed, but you can override it so that it does something else (such as returning a dummy link and logging the error to stderr).
Params:
link is the link that failed to resolve.
Returns:
a replacement string, optionally.
Throws:
exceptions.ValueError by default as explained above.
- global function validSectionName(name: string)
Checks if a given name is a valid name for a doc section.
- global function isPlistEmpty(plist: array)
Checks if a paragraph list is empty (has no actual text).
- global function isDocsEmpty(doctable: table)
Checks if a given doctable's docs member is an empty plist.
- global function numToRoman(n: int, lower: bool)
Converts a positive integer to a roman numeral. Only works for numbers in the range 1 to 99; numbers larger than this are wrapped around (100 becomes 1, 101 becomes 2, etc.).
Params:
n is the number.
lower is whether or not the result should be lowercase.
Returns:
a string.
Throws:
exceptions.RangeError if n <= 0.
- global function numToLetter(n: int, lower: bool)
Converts a positive integer to a letter of the alphabet. Only works for numbers in the range 1 to 26; numbers larger than this are wrapped around.
Params:
n is the number.
lower is whether or not the result should be lowercase.
Returns:
a string.
Throws:
exceptions.RangeError if n <= 0.
- global function toHeader(doctable: table, parentFQN: string, full: bool = true)
Given a doctable, returns a string which would make a suitable documentation header for that item.
If the full parameter is true (the default), you will get headers that look like this:
For modules, it will be of the form "module name".
For functions, it will be of the form "functionName(parameters)", where parameters will be a listing of all parameter names, their types (if not trivial), and any default values. Some examples:
"this()" (for any function named "constructor")
"someFunction()"
"anotherFunction(x: int)"
"staticMethod(this: class, param: string = 'hi')"
"variadicFunc(fmt: string, vararg)"
For classes and namespaces, it will look like the first line of the declaration, like "class Foo : Bar" or "namespace N".
For fields, it will be the name of the field, followed by the initializer if it has one. Examples: "_x", "numThings = 0".
For variables, it will look just like the variable declaration, like "local a = 4" or "global y".
If the full parameter is false, then all you will get back is the name of the item as follows.
Regardless of the full parameter, if the parentFQN parameter is a non-empty string, the name of the item will be prepended with parentFQN followed by a period; that is, if parentFQN is "some.mod" and doctable.name is "foo", then this will result in the name "some.mod.foo" in the result. If parentFQN is the empty string, then the name in the result will simply be "foo".
Params:
doctable is the item to get a header of.
parentFQN is the fully-qualified name of doctable's owner, or the empty string if you don't want the owner's name to be prepended to the item name.
full controls whether the header is full or just the name, as explained above.
Returns:
a string containing the header representation.
Throws:
exceptions.ValueError if doctable's kind is "parameter" or some invalid kind.
- global stdSections = [...
Defines the order of the standard sections that the SectionOrder class uses by default.
The order is:
deprecated
docs
examples
params
returns
throws
bugs
notes
todo
warnings
see
authors
date
history
since
version
copyright
license
- class SectionOrder
Defines an ordering of sections as used by documentation visitors.
- SectionOrder.this()
The new instance will have its order set to the same order as defined in stdSections.
- function SectionOrder.dup()
Duplicates this order.
Returns:
a new instance of this class.
- function SectionOrder.getOrder()
Returns:
the current order as an array.
- function SectionOrder.setOrder(order: array)
Sets the current order to the given array. It must satisfy all of the following conditions:
All elements of order must be strings.
All elements must be valid section names as defined by validSectionName.
All of the standard sections must appear in the order.
No section appears twice in the order.
Params:
order order is the new order as described above.
Throws:
exceptions.ValueError if any of the given constraints are not satisfied.
- function SectionOrder.insertSectionBefore(sec: string, before: string)
Moves the section sec before the existing section before.
Params:
sec is the name of the section to insert. It can be a section already in the order, in which case it will be moved; or a new section name.
before is the name of the section before which sec will be inserted.
- function SectionOrder.insertSectionAfter(sec: string, after: string)
Same as insertSectionBefore, but puts sec after after instead of before it.
- class DocOutputter
This class defines an "outputter" interface which works in conjunction with the OutputDocVisitor class.
The general idea of this interface is that for each doc item, section, paragraph, and paragraph element, the owning OutputDocVisitor will call the begin method for it, then process its contents, and then call the corresponding end method. For instance, when visiting a module, it calls beginModule, then processes the module's documentation and its children, and finally calls endModule.
Note that there is no requirement to use either of these classes; you can simply write your own doc visitor if you wish. However this interface tends to work well for many kinds of doc outputs, and saves you from having to rewrite some stuff over and over.
- function DocOutputter.beginModule(doctable: table)
function DocOutputter.endModule()
function DocOutputter.beginFunction(doctable: table)
function DocOutputter.endFunction()
function DocOutputter.beginClass(doctable: table)
function DocOutputter.endClass()
function DocOutputter.beginNamespace(doctable: table)
function DocOutputter.endNamespace()
function DocOutputter.beginField(doctable: table)
function DocOutputter.endField()
function DocOutputter.beginVariable(doctable: table)
function DocOutputter.endVariable() Each of these pairs of methods is called when the visitor encounters a doc item of the given type.
In the begin methods, your implementation is expected to handle any dittos as well (which will be in the doctable param if any exist).
Params:
doctable is the doc table of the given item.
- function DocOutputter.beginSection(name: string)
Called when a given section begins.
The sections are output in whatever order is specified by the visitor, so you shouldn't depend on them being output in any specific order.
Note that the "params" and "throws" sections will call some additional methods between their begin and end calls, listed below
Params:
name is the name of the section, completely unmodified (so it will be lowercase and, if it's a custom section, will still have the underscore at the beginning).
- function DocOutputter.endSection()
Called when a section ends.
- function DocOutputter.beginParameter(doctable: table)
When outputting a "params" section, this is called for each parameter.
This method is passed the parameter's doctable, so that it can output the name/type/default value/whatever it wants. The docs, however, will be output by the OutputDocVisitor after this method returns, so you don't have to output those yourself.
Params:
doctable is the doctable of the parameter being begun.
- function DocOutputter.endParameter()
Called when a parameter ends.
- function DocOutputter.beginException(name: string)
When outputting a "throws" section, this is called for each exception.
This is similar to the beginParameter method in that this will be called, and after it returns, the docs for the exception will be output.
Params:
name is the exception name.
- function DocOutputter.endException()
Called when an exception ends.
- function DocOutputter.outputText(vararg)
Output raw text.
This is called to output raw text snippets in paragraphs, among other things.
Params:
vararg are all strings to be output.
- function DocOutputter.beginParagraph()
function DocOutputter.endParagraph() Begin and end a single paragraph as defined by the doc comment spec.
Between these calls, you'll get calls to output the paragraph's contents.
- function DocOutputter.beginCode(language: string)
function DocOutputter.endCode()
function DocOutputter.beginVerbatim(type: string)
function DocOutputter.endVerbatim() Begin and end code and verbatim sections.
The language parameter of beginCode is what programming language the code snippet is in.
Within these sections, only outputText will be called.
- function DocOutputter.beginBulletList()
function DocOutputter.endBulletList()
function DocOutputter.beginNumList(type: string)
function DocOutputter.endNumList() Begin and end bulleted and numbered lists.
The type parameter of beginNumList specifies the type of list (one of "1", "a", "A", "i", and "I").
- function DocOutputter.beginListItem()
function DocOutputter.endListItem() Begin and end list items in bulleted and numbered lists.
Each list item will be bracketed by these two calls. Sub-lists are not treated as their own list items.
- function DocOutputter.beginDefList()
function DocOutputter.endDefList() Begin and end definition lists.
Each item will consist of a definition term followed by a definition ... definition. Hey, you come up with a better name!
- function DocOutputter.beginDefTerm()
function DocOutputter.endDefTerm()
function DocOutputter.beginDefDef()
function DocOutputter.endDefDef() Begin and end definition list items.
For each item, you will get a beginDefTerm, then some paragraph elements for the term, then endDefTerm; then comes beginDefDef, then the contents of the definition, and finally endDefDef.
- function DocOutputter.beginTable()
function DocOutputter.endTable()
function DocOutputter.beginRow()
function DocOutputter.endRow()
function DocOutputter.beginCell()
function DocOutputter.endCell() Begin and end tables, their rows, and their cells.
Each row is bracketed by beginRow/endRow calls; each cell in each row is bracketed by beginCell/endCell calls. It's simple.
- function DocOutputter.beginBold()
function DocOutputter.endBold()
function DocOutputter.beginEmphasis()
function DocOutputter.endEmphasis()
function DocOutputter.beginStrikethrough()
function DocOutputter.endStrikethrough()
function DocOutputter.beginSubscript()
function DocOutputter.endSubscript()
function DocOutputter.beginSuperscript()
function DocOutputter.endSuperscript()
function DocOutputter.beginMonospace()
function DocOutputter.endMonospace()
function DocOutputter.beginUnderline()
function DocOutputter.endUnderline() Begin and end text spans.
- function DocOutputter.beginLink(link: string)
function DocOutputter.endLink() Begin and end link text spans.
Params:
link is the link target, and if you want the link to work, you'll have to use a LinkResolver with an implementation of LinkTranslator to do so.
- function DocOutputter.beginModule(doctable: table)
- class OutputDocVisitor : DocVisitor
A kind of doc visitor which uses an instance of a class derived from DocOutputter to output documentation.
If you want to handle sections with custom formatting and custom spans in your documentation when using this little framework, you can derive from this class and override the appropriate methods.
- OutputDocVisitor.this(so, o)
Params:
so is the order in which the sections should be visited for each documentation item.
o is an instance of a class derived from DocOutputter which implements its interface.
- function OutputDocVisitor.visitModule(doctable: table)
function OutputDocVisitor.visitFunction(doctable: table)
function OutputDocVisitor.visitClass(doctable: table)
function OutputDocVisitor.visitNamespace(doctable: table)
function OutputDocVisitor.visitField(doctable: table)
function OutputDocVisitor.visitVariable(doctable: table) Each of these visits a documentation item of the given type.
By default, they call the appropriate begin method on the outputter, then output any docs for the item, then (if applicable) it recursively visits its children, and finally calls the appropriate end method. You can override a method if you want to do something different.
Params:
doctable is the item's doc table.
- function OutputDocVisitor.visitSection(name: string, contents: array)
Visits one section of an item's docs, outputting them if necessary.
For "docs" sections, no begin/endSection methods will be called if the section is empty.
For "params" sections, no begin/endSection methods will be called if all of the parameters' docs are empty.
For "params" and "throws" sections, calls the begin/endParameter and begin/endException methods as defined in DocOutputter.
For all other kinds of sections, simply calls the beginSection method, then outputs its contents as a list of paragraphs, and then calls the endSection method.
This handles "regular" custom sections as well, but if you have a custom section which expects specific formatting, you can override this method and handle that section appropriately.
Params:
name is the name of the section, unmodified from the doctables.
contents is a plist as defined by the doc comment spec.
- function OutputDocVisitor.visitParagraph(par: array)
Override of docs.DocVisitor.visitParagraph which simply calls the begin/endParagraph methods around the paragraph's contents.
- function OutputDocVisitor.visitText(elem: string)
Simply calls the outputter's outputText with its input as the parameter.
- function OutputDocVisitor.visitCode(language: string, contents: string)
function OutputDocVisitor.visitVerbatim(type: string, contents: string)
function OutputDocVisitor.visitBlist(items: array)
function OutputDocVisitor.visitNlist(type: string, items: array)
function OutputDocVisitor.visitDlist(items: array)
function OutputDocVisitor.visitTable(rows: array)
function OutputDocVisitor.visitBold(contents: array)
function OutputDocVisitor.visitEmphasis(contents: array)
function OutputDocVisitor.visitLink(link: string, contents: array)
function OutputDocVisitor.visitStrikethrough(contents: array)
function OutputDocVisitor.visitSubscript(contents: array)
function OutputDocVisitor.visitSuperscript(contents: array)
function OutputDocVisitor.visitMonospace(contents: array)
function OutputDocVisitor.visitUnderline(contents: array)
function OutputDocVisitor.visitCustomSpan(type: string, contents: array) Implmentations of the methods which output text structures and spans.
- function OutputDocVisitor._doDocSections(doctable: table)
Protected method which implements the section visiting.
This is called from the item visit methods, and calls the visitSection method for any section that exists in the given doctable. You can override this if you need different handling.
Params:
doctable is the doctable of the item that's being visited.
by Victor Nakoryakov; Page generated on 15 Nov 2014 10:28:14