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 new taglets. 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 and usage 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 use module()

• 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 as ldoc . 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. In config.ld this can also be a table of files and directories.
• project name of project, used as title in top left
• title page title, default ‘Reference’
• package explicit base package name; also used for resolving references in documents
• all show local functions, etc as well in the docs
• format 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 style
• boilerplate ignore first comment in all source files (e.g. license comments)
• ext extension for output (default ‘html’)
• one use a one-column layout
• style, template: together these specify the directories for the style and and the template. In config.ld they may also be true, 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 title
• full_description when you really need a longer project description
• examples a directory or file: can be a table
• readme or topics 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 order
• no_return_or_parms don’t show parameters or return values in output
• no_lua_ref stop obsessively trying to create references to standard Lua libraries
• backtick_references whether references in backticks will be resolved. Happens by default when using Markdown. When explicit will expand non-references in backticks into <code> elements
• plain set to true if format is set but you don’t want code comments processed
• wrap set to true if you want to allow long names to wrap in the summaries
• manual_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 summary
• custom_tags define some new tags, which will be presented after the function description. The format is {<name>,[title=<name>,}{hidden=false,}{format=nil}}. For instance custom_tags={'remark',title='Remarks'} will add a little Remarks 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. Markdown
• custom_see_handler function that filters see-references
• custom_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 like isdir,isfile,exists, splitting paths like dirname and basename
• dir: listing files in directories (getfiles,getallfiles) and creating/removing directory paths
• file: copy,move; read/write contents with read and write

Application Support

• app: require_here to rebase require to work with main script path; simple argument parsing parse_args
• lapp: sophisticated usage-text-driven argument parsing for applications
• config: flexibly read Unix config files and Windows INI files
• strict: check for undefined global variables - can use strict.module for modules
• utils,compat: Penlight support for unified Lua 5.1/5.2 codebases
• types: predicates like is_callable and is_integer; extended type function.

Extra String Operations

• utils: can split a string with a delimiter using utils.split
• stringx: extended string functions covering the Python string type
• stringio: open strings for reading, and creating strings using standard Lua IO methods
• lexer: lexical scanner for splitting text into tokens; special cases for Lua and C
• text: indenting and dedenting text, wrapping paragraphs; optionally make % work as in Python
• template: small but powerful template expansion engine
• sip: Simple Input Patterns - higher-level string patterns for parsing text

Extra Table Operations

• tablex: copying, comparing and mapping over
• pretty: pretty-printing Lua tables, and various safe ways to load Lua as data
• List: implementation of Python 'list' type - slices, concatenation and partitioning
• Map, Set, OrderedMap: classes for specialized kinds of tables
• data: reading tabular data into 2D arrays and efficient queries
• array2d: operations on 2D arrays
• permute: generate permutations

Iterators, OOP and Functional

• seq: working with iterator pipelines; collecting iterators as tables
• class: a simple reusable class framework
• func: symbolic manipulation of expressions and lambda expressions
• utils: utils.string_lambda converts short strings like '|x| x^2' into functions
• comprehension: 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/