build/luadoc/luadoc/doclet/formatter.lua

   1 -------------------------------------------------------------------------------
   2 -- Doclet to format source code according to LuaDoc standard tags. This doclet
   3 -- (re)write .lua files adding missing standard tags. Texts are formatted to
   4 -- 80 columns and function parameters are added based on code analysis.
   5 --
   6 -- @release $Id: formatter.lua,v 1.5 2007/04/18 14:28:39 tomas Exp $
   7 -------------------------------------------------------------------------------
   8
   9 local util = require "luadoc.util"
  10 local assert, ipairs, pairs, type = assert, ipairs, pairs, type
  11 local string = require"string"
  12 local table = require"table"
  13
  14 module "luadoc.doclet.formatter"
  15
  16 options = {
  17         output_dir = "./",
  18 }
  19
  20 -------------------------------------------------------------------------------
  21 -- Assembly the output filename for an input file.
  22 -- TODO: change the name of this function
  23 function out_file (filename)
  24         local h = filename
  25         h = options.output_dir..h
  26         return h
  27 end
  28
  29 -------------------------------------------------------------------------------
  30 -- Generate a new lua file for each input lua file. If the user does not
  31 -- specify a different output directory input files will be rewritten.
  32 -- @param doc documentation table
  33
  34 function start (doc)
  35         local todo = "<TODO>"
  36
  37         -- Process files
  38         for i, file_doc in ipairs(doc.files) do
  39                 -- assembly the filename
  40                 local filename = out_file(file_doc.name)
  41                 luadoc.logger:info(string.format("generating file `%s'", filename))
  42
  43                 -- TODO: confirm file overwrite
  44                 local f = posix.open(filename, "w")
  45                 assert(f, string.format("could not open `%s' for writing", filename))
  46
  47                 for _, block in ipairs(file_doc.doc) do
  48
  49                         -- write reorganized comments
  50                         f:write(string.rep("-", 80).."\n")
  51
  52                         -- description
  53                         f:write(util.comment(util.wrap(block.description, 77)))
  54                         f:write("\n")
  55
  56                         if block.class == "function" then
  57                                 -- parameters
  58                                 table.foreachi(block.param, function (_, param_name)
  59                                         f:write(util.comment(util.wrap(string.format("@param %s %s", param_name, block.param[param_name] or todo), 77)))
  60                                         f:write("\n")
  61                                 end)
  62
  63                                 -- return
  64                                 if type(block.ret) == "table" then
  65                                         table.foreachi(block.ret, function (_, ret)
  66                                                 f:write(util.comment(util.wrap(string.format("@return %s", ret), 77)).."\n")
  67                                         end)
  68                                 else
  69                                         f:write(util.comment(util.wrap(string.format("@return %s", block.ret or todo), 77)).."\n")
  70                                 end
  71                         end
  72
  73                         -- TODO: usage
  74                         -- TODO: see
  75
  76                         -- write code
  77                         for _, line in ipairs(block.code) do
  78                                 f:write(line.."\n")
  79                         end
  80                 end
  81
  82                 f:close()
  83         end
  84 end