From 8c3ee6f9b7e5ab0b4edbf4838c7c1a9ee6d7df5d Mon Sep 17 00:00:00 2001 From: Steven Barth Date: Tue, 29 Jul 2008 21:16:12 +0000 Subject: [PATCH] Added "apidocs" target to Makefile contrib/luadoc: Added luadoc executable libs: Fixed typos in inline documentation --- .gitignore | 1 + Makefile | 4 + build/makedocs.sh | 2 + contrib/luadoc/hostfiles/bin/luadoc | 121 ++++++++++++++++++++++++++++ libs/core/luasrc/util.lua | 2 +- libs/web/luasrc/dispatcher.lua | 4 +- 6 files changed, 131 insertions(+), 3 deletions(-) create mode 100755 build/makedocs.sh create mode 100755 contrib/luadoc/hostfiles/bin/luadoc diff --git a/.gitignore b/.gitignore index 689c4de7aa..27b6e758b5 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ dist/ *.o *.so *.swp +/docs diff --git a/Makefile b/Makefile index 12c1d89e09..a9e5e1eb23 100644 --- a/Makefile +++ b/Makefile @@ -18,6 +18,7 @@ luabuild: for i in $(MODULES); do make -C$$i lua$(LUA_TARGET); done clean: + rm -rf docs for i in $(MODULES); do make -C$$i clean; done @@ -58,6 +59,9 @@ runshell: hostenv hostclean: clean rm -rf host +apidocs: hostenv + build/hostenv.sh $(realpath host) $(LUA_MODULEDIR) $(LUA_LIBRARYDIR) "build/makedocs.sh host/luci/ docs" + run: # make run is deprecated # # Please use: # diff --git a/build/makedocs.sh b/build/makedocs.sh new file mode 100755 index 0000000000..2f7f573450 --- /dev/null +++ b/build/makedocs.sh @@ -0,0 +1,2 @@ +luadoc -d $2 --no-files $(for f in $(find $1 -name '*.lua' -type f); do if grep -q -- "@return" $f; then echo $f; fi; done) +echo API-Documentation was created in $2. diff --git a/contrib/luadoc/hostfiles/bin/luadoc b/contrib/luadoc/hostfiles/bin/luadoc new file mode 100755 index 0000000000..ba99a3775e --- /dev/null +++ b/contrib/luadoc/hostfiles/bin/luadoc @@ -0,0 +1,121 @@ +#!/usr/bin/env lua +------------------------------------------------------------------------------- +-- LuaDoc launcher. +-- @release $Id: luadoc.lua.in,v 1.1 2008/02/17 06:42:51 jasonsantos Exp $ +------------------------------------------------------------------------------- + +require "luadoc" + +------------------------------------------------------------------------------- +-- Print version number. + +local function print_version () + print (string.format("%s\n%s\n%s", + luadoc._VERSION, + luadoc._DESCRIPTION, + luadoc._COPYRIGHT)) +end + +------------------------------------------------------------------------------- +-- Print usage message. + +local function print_help () + print ("Usage: "..arg[0]..[[ [options|files] +Generate documentation from files. Available options are: + -d path output directory path + -t path template directory path + -h, --help print this help and exit + --noindexpage do not generate global index page + --nofiles do not generate documentation for files + --nomodules do not generate documentation for modules + --doclet doclet_module doclet module to generate output + --taglet taglet_module taglet module to parse input code + -q, --quiet suppress all normal output + -v, --version print version information]]) +end + +local function off_messages (arg, i, options) + options.verbose = nil +end + +------------------------------------------------------------------------------- +-- Process options. TODO: use getopts. +-- @class table +-- @name OPTIONS + +local OPTIONS = { + d = function (arg, i, options) + local dir = arg[i+1] + if string.sub (dir, -2) ~= "/" then + dir = dir..'/' + end + options.output_dir = dir + return 1 + end, + t = function (arg, i, options) + local dir = arg[i+1] + if string.sub (dir, -2) ~= "/" then + dir = dir..'/' + end + options.template_dir = dir + return 1 + end, + h = print_help, + help = print_help, + q = off_messages, + quiet = off_messages, + v = print_version, + version = print_version, + doclet = function (arg, i, options) + options.doclet = arg[i+1] + return 1 + end, + taglet = function (arg, i, options) + options.taglet = arg[i+1] + return 1 + end, +} + +------------------------------------------------------------------------------- + +local function process_options (arg) + local files = {} + local options = require "luadoc.config" + local i = 1 + while i <= #arg do + local argi = arg[i] + if string.sub (argi, 1, 1) ~= '-' then + table.insert (files, argi) + else + local opt = string.sub (argi, 2) + if string.sub (opt, 1, 1) == '-' then + opt = string.gsub (opt, "%-", "") + end + if OPTIONS[opt] then + if OPTIONS[opt] (arg, i, options) then + i = i + 1 + end + else + options[opt] = 1 + end + end + i = i+1 + end + return files, options +end + +------------------------------------------------------------------------------- +-- Main function. Process command-line parameters and call luadoc processor. + +function main (arg) + -- Process options + local argc = #arg + if argc < 1 then + print_help () + return + end + local files, options = process_options (arg) + return luadoc.main(files, options) +end + +main(arg) diff --git a/libs/core/luasrc/util.lua b/libs/core/luasrc/util.lua index bcd4ed1e05..a4ea2d29f8 100644 --- a/libs/core/luasrc/util.lua +++ b/libs/core/luasrc/util.lua @@ -320,7 +320,7 @@ end --- Combines two or more numerically indexed tables into one. -- @param tbl1 Table value to combine -- @param tbl2 Table value to combine --- @param tblN More values to combine +-- @param ... More tables to combine -- @return Table value containing all values of given tables function combine(...) local result = {} diff --git a/libs/web/luasrc/dispatcher.lua b/libs/web/luasrc/dispatcher.lua index 628b4e3ee7..576db36b41 100644 --- a/libs/web/luasrc/dispatcher.lua +++ b/libs/web/luasrc/dispatcher.lua @@ -410,7 +410,7 @@ function rewrite(n, ...) end --- Create a function-call dispatching target. --- @param nane Target function of local controller +-- @param name Target function of local controller -- @param ... Additional parameters passed to the function function call(name, ...) local argv = {...} @@ -418,7 +418,7 @@ function call(name, ...) end --- Create a template render dispatching target. --- @param nane Template to be rendered +-- @param name Template to be rendered function template(name) require("luci.template") return function() luci.template.render(name) end -- 2.30.2