Lua Doc生成工具_Lua_脚本语言_编程语言

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}