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生成工具的更多相关文章
- 【Lua】LDoc生成Lua文档工具的使用
参考资料: http://my.oschina.net/wangxuanyihaha/blog/188909 LDoc介绍: LDoc是一个Lua的文档生成工具,过去,比较常用的Lua生成 ...
- 数据字典生成工具之旅(5):DocX组件读取与写入Word
由于上周工作比较繁忙,所以这篇文章等了这么久才写(预告一下,下一个章节正式进入NVelocity篇,到时会讲解怎么使用NVelocity做一款简易的代码生成器,敬请期待!),好了正式进入本篇内容. 这 ...
- 赞!jsPDF – 基于 HTML5 的强大 PDF 生成工具
jsPDF 是一个基于 HTML5 的客户端解决方案,用于生成各种用途的 PDF 文档.使用方法很简单,只要引入 jsPDF 库,然后调用内置的方法就可以了.浏览器兼容性: IE 10, Firefo ...
- JS文档和Demo自动化生成工具 - SmartDoc发布
曾几何时,当你码神附体,一路披荆斩棘的完成代码后,带着“一码在手,天下我有”的傲然环顾之时,却发现单元测试.API文档.Demo实例陆续向你砸来,顿时有木有一种冰水挑战后的感觉.而这时你应该:哟哟,快 ...
- 使用Objective-C的文档生成工具:appledoc
使用Objective-C的文档生成工具:appledoc 前言 做项目的人多了,就需要文档了.今天开始尝试写一些项目文档.但是就源代码来说,文档最好和源码在一起,这样更新起来更加方便和顺手.象 Ja ...
- Lua内存分析工具
最近给公司写了一个lua内存分析工具,可以非常方便的分析出Lua内存泄露问题,有图形化界面操作,方便手机端上传快照等功能 内存分析我是在c语言端写的,也有人写过lua端的分析工具,也蛮好用的,不过lu ...
- Markdown 文档生成工具
之前用了很多Markdown 文档生成工具,发现有几个挺好用的,现在整理出来,方便大家快速学习. loppo: 非常简单的静态站点生成器 idoc:简单的文档生成工具 gitbook:大名鼎鼎的文档协 ...
- python文档生成工具:pydoc、sphinx;django如何使用sphinx?
文档生成工具: 自带的pydoc,比较差 建议使用sphinx 安装: pip install sphinx 安装主题: 由各种主题,我选择常用的sphinx_rtd_theme pip instal ...
- H5类似易企秀/编辑器/页面制作/开发/生成工具/软件/源码/授权
代码地址如下:http://www.demodashi.com/demo/14960.html 项目简介 H5DS (HTML5 Design software) 这是一款基于WEB的 H5制作工具. ...
随机推荐
- jmeter生成测试报告
- Equivalent Sets HDU - 3836 (Tarjan)
题目说给出一些子集,如果A是B的子集,B是A的子集,那么A和B就是相等的,然后给出n个集合m个关系,m个关系表示u是v的子集,问你最小再添加多少个关系可以让这n个集合都是相等的 如果这n个几个都是互相 ...
- jackson json转对象 对象转json
一,Jackson使用示例 第1步:创建ObjectMapper对象. 创建ObjectMapper对象.它是一个可重复使用的对象. ObjectMapper mapper = new ObjectM ...
- ArcGIS for qml - 地址地标转换为经纬度(地理编码)
实现输入地址地标转换为其经纬度 本文链接:地理编码 作者: 狐狸家的鱼 Github: 八至 一.地理编码 1.地理编码含义 地址编码(或地理编码)是使用地址中包含的信息来插入地图上的相应位置的过程. ...
- [luogu4626][一道水题2]
题目链接 思路 这个首先想到质因数分解.然后发现只要对于每个质数将ans乘以这个质数在从1到n中出现过的最高指数次就行了. 这个\(10^8\)令人发指.一直tle,最后发现吸口氧才能过.. 代码 # ...
- Vue+koa2开发一款全栈小程序(3.vue入门、Mpvue入门)
1.Vue-cli 1.新建一个vue项目 打开cmd 官方命令行工具 npm install -g vue-cli //安装脚手架 cd到你想要存放demo的目录下,然后 vue init webp ...
- 关于form与表单操作
form表单自动提交规则 form表单中只有一个type=text的input,在input中按enter键,会自动提交: form表单中有多个type=text的input,且无type=submi ...
- Python之常用模块--collections模块
认识模块 什么是模块? 常见的场景:一个模块就是一个包含了python定义和声明的文件,文件名就是模块名字加上.py的后缀. 但其实import加载的模块分为四个通用类别: 1 使用python编写的 ...
- 浅谈CSRF(Cross-site request forgery)跨站请求伪造(写的非常好)
一 CSRF是什么 CSRF(Cross-site request forgery)跨站请求伪造,也被称为“One Click Attack”或者Session Riding,通常缩写为CSRF或者X ...
- JS怎么判断一个对象是否为空
昨天面试的时候被问到的问题.只怪自己根基不牢,没有回答好 甚至说出了“判断这个obj是否和{}相等”这样鱼蠢的答案(/(ㄒoㄒ)/~~)引用类型怎么可以直接判断==或者===呢?! 今天中秋佳节,宝宝 ...