Lua Doc生成工具
Luadoc
http://keplerproject.github.io/luadoc/
Overview
LuaDoc is a documentation generator tool for Lua source code. It parses the declarations and documentation comments in a set of Lua source files and produces a set of XHTML pages describing the commented declarations and functions.
The output is not limited to XHTML. Other formats can be generated by implementing new
doclets
. The format of the documentation comments is also flexible and can be customized by implementing newtaglets
. Please refer to customizing section for further information.LuaDoc is free software and uses the same license as Lua.
LDoc
https://github.com/stevedonovan/LDoc
A LuaDoc-compatible documentation generation system http://stevedonovan.github.com/ldoc/
Rationale
This project grew out of the documentation needs of Penlight (and not always getting satisfaction with LuaDoc) and depends on Penlight itself.(This allowed me to not write a lot of code.)
The API documentation of Penlight is an example of a project using plain LuaDoc markup processed using LDoc.
LDoc is intended to be compatible with LuaDoc and thus follows the pattern set by the various *Doc tools:
--- Summary ends with a period. -- Some description, can be over several lines. -- @param p1 first parameter -- @param p2 second parameter -- @return a string value -- @see second_fun function mod1.first_fun(p1,p2) end
Tags such as
see
andusage
are supported, and generally the names of functions and modules can be inferred from the code.LDoc is designed to give better diagnostics: if a
@see
reference cannot be found, then the line number of the reference is given. LDoc knows about modules which do not usemodule()
- this is important since this function has become deprecated in Lua 5.2. And you can avoid having to embed HTML in commments by using Markdown.
LDoc will also work with Lua C extension code, and provides some convenient shortcuts.
An example showing the support for named sections and ‘classes‘ is the Winapi documentation; this is generated from winapi.l.c.
LDoc API & Help
http://stevedonovan.github.io/ldoc/manual/doc.md.html#Basic_Usage
LDoc, a Lua Documentation Tool
Introduction
LDoc is a software documentation tool which automatically generates API documentation out of source code comments (doc comments). It is mainly targeted at Lua and documenting Lua APIs, but it can also parse C with according doc comments for documenting Lua modules implemented in C.
It is mostly compatible with LuaDoc, except that certain workarounds are no longer needed. For instance, it is not so married to the idea that Lua modules should be defined using the
module
function; this is not only a matter of taste since this has been deprecated in Lua 5.2.Otherwise, the output is very similar, which is no accident since the HTML templates are based directly on LuaDoc. You can ship your own customized templates and style sheets with your own project (also see Graham Hannington’s documentation for Lua for z/OS). LDoc comes with three extra themes; ‘pale’ for those who like whitespace, ‘one’ for one-column output, and ‘fixed’ for a fixed navigation bar down the left side.
You have an option to use Markdown to process the documentation, which means no ugly HTML is needed in doc comments. C/C++ extension modules may be documented in a similar way, although function names cannot be inferred from the code itself.
LDoc can provide integrated documentation, with traditional function comments, any documents in Markdown format, and specified source examples. Lua source in examples and the documents will be prettified.
Although there are a fair number of command-line options, the preferred route is to write a
config.ld
configuration file in Lua format. By convention, if LDoc is simply invoked asldoc .
it will read this file first. In this way, the aim is to make it very easy for end-users to build your documentation using this simple command.
------------
Here are all the tags known to LDoc:
- @module A Lua module containing functions and tables, which may be inside sections
- @classmod Like @module but describing a class
- @submodule A file containing definitions that you wish to put into the named master module
- @script A Lua program
- @author (multiple), copyright, @license, @release only used for project-level tags like @module
- @function, @lfunction. Functions inside a module
- @param formal arguments of a function (multiple)
- @return returned values of a function (multiple)
- @raise unhandled error thrown by this function
- @local explicitly marks a function as not being exported (unless
--all
)- @see reference other documented items
- @usage give an example of a function’s use. (Has a somewhat different meaning when used with @module)
- @table a Lua table
- @field a named member of a table
- @section starting a named section for grouping functions or tables together
- @type a section which describes a class
- @within puts the function or table into an implicit section
- @fixme, @todo and @warning are annotations, which are doc comments that occur inside a function body.
http://stevedonovan.github.io/ldoc/manual/doc.md.html#Basic_Usage
Fields allowed in
config.ld
Same meaning as the corresponding parameters:
file
a file or directory containing sources. Inconfig.ld
this can also be a table of files and directories.project
name of project, used as title in top lefttitle
page title, default ‘Reference’package
explicit base package name; also used for resolving references in documentsall
show local functions, etc as well in the docsformat
markup processor, can be ‘plain’ (default), ‘markdown’ or ‘discount’output
output name (default ‘index’)dir
directory for output files (default ‘doc’)colon
use colon style, instead of @ tag styleboilerplate
ignore first comment in all source files (e.g. license comments)ext
extension for output (default ‘html’)one
use a one-column layoutstyle
,template
: together these specify the directories for the style and and the template. Inconfig.ld
they may also betrue
, meaning use the same directory as the configuration file.merge
allow documentation from different files to be merged into modules without explicit @submodule tag_These only appear in the configuration file:_
description
a short project description used under the project titlefull_description
when you really need a longer project descriptionexamples
a directory or file: can be a tablereadme
ortopics
readme files (to be processed with Markdown)pretty
code prettify ‘lua’ (default) or ‘lxsh’prettify_files
prettify the source as well and make links to it; if its value is “show” then also index the source files.charset
use if you want to override the UTF-8 default (also @charset in files)sort
set if you want all items in alphabetical orderno_return_or_parms
don’t show parameters or return values in outputno_lua_ref
stop obsessively trying to create references to standard Lua librariesbacktick_references
whether references in backticks will be resolved. Happens by default when using Markdown. When explicit will expand non-references in backticks into<code>
elementsplain
set to true ifformat
is set but you don’t want code comments processedwrap
set to true if you want to allow long names to wrap in the summariesmanual_url
point to an alternative or local location for the Lua manual, e.g. ‘file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html’no_summary
suppress the Contents summarycustom_tags
define some new tags, which will be presented after the function description. The format is{<name>,[title=<name>,}{hidden=false,}{format=nil}}
. For instancecustom_tags={‘remark‘,title=‘Remarks‘}
will add a littleRemarks
section to the docs for any function containing this tag.format
can be a function – if not present the default formatter will be used, e.g. Markdowncustom_see_handler
function that filters see-referencescustom_display_name_handler
function that formats an item’s name. The arguments are the item and the default function used to format the name. For example, to show an icon or label beside any function tagged with a certain tag:
LDoc demo
http://stevedonovan.github.io/ldoc/examples/mylib.c.html
/// A sample C extension.
// Demonstrates using ldoc‘s C/C++ support. Can either use /// or /*** */ etc.
// @module mylib
#include <string.h>
#include <math.h>
// includes for Lua
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>
/***
Create a table with given array and hash slots.
@function createtable
@param narr initial array slots, default 0
@param nrec initial hash slots, default 0
*/
static int l_createtable (lua_State *L) {
int narr = luaL_optint(L,1,0);
int nrec = luaL_optint(L,2,0);
lua_createtable(L,narr,nrec);
return 1;
}
-------------
------
-- Various ways of indicating errors
-- @module multiple
-----
-- function with return groups.
-- @treturn[1] string result
-- @return[2] nil
-- @return[2] error message
function mul1 () end
LDoc 依賴 PenLight 庫
https://github.com/stevedonovan/Penlight
Penlight brings together a set of generally useful pure Lua modules, focusing on input data handling (such as reading configuration files), functional programming (such as map, reduce, placeholder expressions, etc), and OS path management. Much of the functionality is inspired by the Python standard libraries.
Paths, Files and Directories
path
: queries likeisdir
,isfile
,exists
, splitting paths likedirname
andbasename
dir
: listing files in directories (getfiles
,getallfiles
) and creating/removing directory pathsfile
:copy
,move
; read/write contents withread
andwrite
Application Support
app
:require_here
to rebaserequire
to work with main script path; simple argument parsingparse_args
lapp
: sophisticated usage-text-driven argument parsing for applicationsconfig
: flexibly read Unix config files and Windows INI filesstrict
: check for undefined global variables - can usestrict.module
for modulesutils
,compat
: Penlight support for unified Lua 5.1/5.2 codebasestypes
: predicates likeis_callable
andis_integer
; extendedtype
function.Extra String Operations
utils
: can split a string with a delimiter usingutils.split
stringx
: extended string functions covering the Pythonstring
typestringio
: open strings for reading, and creating strings using standard Lua IO methodslexer
: lexical scanner for splitting text into tokens; special cases for Lua and Ctext
: indenting and dedenting text, wrapping paragraphs; optionally make%
work as in Pythontemplate
: small but powerful template expansion enginesip
: Simple Input Patterns - higher-level string patterns for parsing textExtra Table Operations
tablex
: copying, comparing and mapping overpretty
: pretty-printing Lua tables, and various safe ways to load Lua as dataList
: implementation of Python ‘list‘ type - slices, concatenation and partitioningMap
,Set
,OrderedMap
: classes for specialized kinds of tablesdata
: reading tabular data into 2D arrays and efficient queriesarray2d
: operations on 2D arrayspermute
: generate permutationsIterators, OOP and Functional
seq
: working with iterator pipelines; collecting iterators as tablesclass
: a simple reusable class frameworkfunc
: symbolic manipulation of expressions and lambda expressionsutils
:utils.string_lambda
converts short strings like ‘|x| x^2‘ into functionscomprehension
: list comprehensions:C‘x for x=1,4‘()=={1,2,3,4}
參考BLOG
http://blog.justbilt.com/2015/08/23/ldoc/
http://www.dpull.com/blog/2016-02-03-ldoc
其它
http://www.cs.scranton.edu/~doc/cppdoc/
CDOC沒有找到。
https://en.wikipedia.org/wiki/Comparison_of_documentation_generators
http://jessevdk.github.io/cldoc/
Lua Doc生成工具