Module:Codedoc

Documentation for this module may be created at Module:Codedoc/doc

-- <nowiki>
--| Reads a file and outputs its comments.
--b Pedro M. Rabinovitch <miller@inf.puc-rio.br>
--$Id: dofile.lua,v 1.2 2003/10/20 03:35:08 miller Exp $
--TODO Check if multiline syntax is working properly
-- Wikifying by Dessamator
local p = {}
local ProcLua = require ('Dev:Codedoc/Procsrc')
local args = require ("Dev:Arguments").getArgs
local opt = { 
        complete = true,
        proc_private = true,
        hideHeader = true
}
--% Creates docs for a module
--@ page (string) A page to read the docs from e.g.  Bananas
--: (string) A string containing the documentation of a module
function p.createDocs(page, defaultPage)
    if defaultPage or (not page) then
        page = ("module:" .. getDefaultPage()) 
    end
    
    local text = mw.title.new( page ):getContent()
    local docOutput = ""
    
    if not text then
        return 
    end
    
    local function processFile()
        return ProcLua:process (text, opt)
    end
    local isValidDoc, cmt = xpcall(processFile, debug.traceback )
    
    if isValidDoc then
        local br = "<br>"
        local scriptInfo =  mw.html.create( 'div' )
        local metaInfo = ""
        
        scriptInfo
            :tag("h2")
                :wikitext("Module information")
                :done()
                
        if not opt.hideHeader then
            metaInfo = cmt.header.authors[1] and "\n;Authors: \n:".. cmt.header.authors[1] or ""..
            cmt.header.purpose and "\n;Purpose: \n:".. cmt.header.purpose or ""..
            cmt.header.revision and "\n;Revision: \n:".. cmt.header.revision or "" ..
            cmt.header.todo[1] and "\n;Todo: \n:".. cmt.header.todo[1] or ""
        end
        if #cmt.functions == 0 then
            return ""
        end
    
        local functionInfo = "\n" ..tostring(createFunctionTables(cmt.functions))
        return tostring(scriptInfo) .. metaInfo .. functionInfo
    else
        return cmt
    end
end
--% Creates tables contains function parameters and return types
--@ functionTable (table) A table containing all functions in the code, related docs
--: (table) A table based on mw.html containing the function docs
function createFunctionTables(functionTable)
    local sFunctions 
    local docOutput = mw.html.create( 'div' )
    local returnData        
    
    docOutput:tag("h3")
        :wikitext("Functions"):done()
    if functionTable then  
        for _, objDetails in pairs(functionTable) do
            docOutput:tag("h4")
                :wikitext(objDetails.name)
                    :done()
                :tag("div")
                    :wikitext(objDetails.purpose)
                        :done()
            sFunctions = mw.html.create( 'table' )
            if objDetails and objDetails.parameters then
                 sFunctions
                    :addClass( 'wikitable' )
                    :addClass( 'sortable' )
                    :css( 'width', '100%' )
                    :tag( 'tr' )
                        :tag( 'th' )
                            :wikitext( 'Name' )
                            :done()
                        :tag( 'th' )
                            :wikitext( 'Type' )
                            :done()
                        :tag( 'th' )
                            :wikitext( 'purpose' )
                            :done()
                        :done()
                docOutput:tag("div")
                    :wikitext("Parameters"):done()
            
                for paramName, paramDetails in pairs(objDetails.parameters) do
                    sFunctions
                    :tag( 'tr' )
                        :tag( 'td' )
                            :wikitext( paramDetails.name )
                            :done()
                        :tag( 'td' )
                            :wikitext (paramDetails.type )
                            :done()
                        :tag( 'td' )
                            :wikitext( paramDetails.purpose )
                            :done()
                        :done()
                end
            end
           
            if objDetails.returns then
                returnData = mw.html.create( 'table' ) 
                    :addClass( 'wikitable' )
                    :addClass( 'sortable' )
                    :css( 'width', '100%' )
                returnData
                    :tag( 'tr' )
                        :tag( 'th' )
                           :wikitext( 'Return type' )
                           :done()
                        :tag( 'th' )
                            :wikitext( 'Return purpose' )
                            :done()
                for _, returnDetails in pairs(objDetails.returns) do
                    returnData
                        :tag( 'tr' )
                            :tag( 'td' )
                                :wikitext( returnDetails.type )
                                :done()
                            :tag( 'td' )
                                :wikitext (returnDetails.purpose )
                                :done()
                end
            end
            docOutput:node(sFunctions)
            if returnData then
                docOutput:node(returnData)
                returnData = nil
            end
        end
    end
    return docOutput
end
--% Entry point for documenting
--@ frame (table) A frame object containing a module name as first parameter
--: (string) The documentation of a particular module
function p.main(frame)
    local page = args(frame)[1]
    local defaultModule = args(frame)["default"] 
    
    if defaultModule  then
        return p.createDocs(nil, true)
    end
    
    local prefix = mw.text.split(page or "", ":")[1] or ""
    
    if  prefix:lower() ~= "module" and page then
        return p.createDocs("module:" .. page)
    end
    
    return p.createDocs(page)
end
--% Gets a default mpage, generally a subpage(e.g"/links") of "Global lua modules"
--: (string) The default page containing documentation
function getDefaultPage()
    local page = mw.text.split(tostring(mw.title.getCurrentTitle()), "/")
    page = page and page[2] or ""
    
    return page
end

return p