commonlib.NPLDocGen

Generating NPL wiki page documentation from source code.

Title Generating NPL wiki page documentation from source code.
Author(s) LiXizhi
Date 2008/3/12, 2008/10/23 gen change log added
File script/ide/NPLDocGen.lua

Description

This class is usually used with the unit test framework, to automatically generate a group of source code documentation from a configuration file

TIP Sample Code

NPL.load("(gl)script/ide/NPLDocGen.lua");
commonlib.NPLDocGen.GenerateTWikiTopic({
   WikiWord = "NPLDocGen",
   ClassName = "commonlib.NPLDocGen",
   input = {"script/ide/NPLDocGen.lua", 
      "script/ide/UnitTest/readme.lua",
   },
})

commonlib.NPLDocGen.GenerateChangeLogWiki({WikiWord = "ParaEngineChangeLog", TopicParent="ParaEngineDoc", HeaderText="---+++ ParaEngine Change History\r\n", input = {"changes.txt"},})

-- When can use the unit test framework, and put lots of below blocks in a single file to batch generate output for many files. 
%TESTCASE{"NPLDocGen", func="commonlib.NPLDocGen.GenerateTWikiTopic", input={WikiWord = "NPLDocGen", ClassName = "commonlib.NPLDocGen", input = {"script/ide/NPLDocGen.lua", "script/ide/mathlib.lua"},}}%

Member Functions

NPLDocGen.WikiInput:new

 default wiki generation input template
NPLDocGen.WikiInput = {
   -- the wiki word for documentation. 
   WikiWord = "NPLDocGen",
   -- array of input files or string script path. 
   -- if file is "*.lua" class and member functions are extracted
   -- if file is "readme.lua" all comment blocks are extracted.  
   -- if file is ".txt" all text are extracted. 
   input = {"script/ide/NPLDocGen.lua", "script/ide/mathlib.lua"},
   -- the output directory. If nil, it will default to script/doc/
   output = "script/doc/",
   -- string or nil, if nil or "", it will be same as WikiWord. Or it can be a fully qualified name, such as "commonlib.NPLDocGen"
   ClassName = nil,
   -- if nil, it defaults to "NPL"
   TopicParent = "NPL",
   -- if the file does not contain an author, use this one. 
   author = "LiXizhi",
   -- a short string description before table of content, this is usually nil.
   desc = nil,
   -- a post processing function string. it applies to "*.txt" and "readme.lua" files in the input. 
   -- such as "NPLDocGen.MakeValidMCMLWikiWords"
   PostProcessor = nil,
   -- a pre processing function string. it applies to all files in the input. 
   -- such as "NPLDocGen.PreProcRPCWrapperToFunction"
   PreProcessor = nil,
   -- if header is ignored, only the context body will be output, and no table of content is generated. 
   IgnoreHeader = nil;
}

create an instance.

syntax

function NPLDocGen.WikiInput:new(o)

parameters

o  

NPLDocGen.GenerateChangeLogWiki


public methods

generate the change log

  • param input : {WikiWord = "ParaEngineChangeLog", TopicParent="ParaEngineDoc", HeaderText="---+++ ParaEngine Change History\r\n", input = {"changes.txt"},}

syntax

function NPLDocGen.GenerateChangeLogWiki(input)

parameters

input {WikiWord = "ParaEngineChangeLog", TopicParent="ParaEngineDoc", HeaderText="---+++ ParaEngine Change History\r\n", input = {"changes.txt"},}

NPLDocGen.GenerateTWikiTopic

[[ generate a wiki page for the given set of input source files twiki requires the following header file, where the second line is optional. %META:TOPICINFO{author="LiXizhi" date="1204269972" format="1.1" reprev="1.1" version="1.1"}% %META:TOPICPARENT{name="TestConvert"}%

  • param input : is a partial pure table of WikiInput
  • see __ : "script/NPL_twiki_doc.lua" for more information.
]]

syntax

function NPLDocGen.GenerateTWikiTopic(input)

parameters

input is a partial pure table of WikiInput

NPLDocGen.GenerateTWikiPortalTopic

[[ generate a portal page with groups and items.

  • see __ : "script/NPL_twiki_doc.lua" for more information.
]]

syntax

function NPLDocGen.GenerateTWikiPortalTopic(input)

parameters

input  

NPLDocGen.ProcessNPLFile


private functions

process NPL source file.

  • param filename : input file name
  • param text : input file text
  • param out : output file object

syntax

function NPLDocGen.ProcessNPLFile(input, filename, text, out)

parameters

input  
filename input file name
text  
out output file object

NPLDocGen.NormalizeReturnString

if the text line seperator "\n" is replaced by "\r\n"

syntax

function NPLDocGen.NormalizeReturnString(text)

parameters

text  

NPLDocGen.GetHeaderInfo

[[ extract header information from the headerText

  • param headerText : a common header looks like below.
Title: Title Text Author(s): LiXizhi Date: 2008/3/12 Desc: description text may be multiple lines Use Lib:
sample code here
  • return __ : it will return a table {Title, Author, Date, Desc, SampleCode}
]]

syntax

function NPLDocGen.GetHeaderInfo(headerText)

parameters

| headerText | a common header looks like below. Title: Title Text Author(s): LiXizhi Date: 2008/3/12 Desc: description text may be multiple lines Use Lib:


sample code here
|

NPLDocGen.ExtractWikiText

body text is assumed to be wiki page, then all comments blocks are extracted and concartinated to a single string.

syntax

function NPLDocGen.ExtractWikiText(bodyText)

parameters

bodyText  

NPLDocGen.GetMemberFunctions

[[ extract array of member functions from string

  • param bodyText : a common function looks like below.
  • return __ : it will return a table {{name="", desc="", syntax="", codes={}, params = {""}, paramsDoc = {a mapping from params name to its description, "return" and "see" are two special param key }, }}
]]

syntax

function NPLDocGen.GetMemberFunctions(bodyText)

parameters

bodyText a common function looks like below.

NPLDocGen.DoTableDefVerbatim


common replacer

if text contains a table definition like table1 = { } it will be encapsulated with verbatim block

syntax

function NPLDocGen.DoTableDefVerbatim(text)

parameters

text  

NPLDocGen.RemoveCommentHeader

if text contains "\r\n--" and other comment styles, it will be removed.

syntax

function NPLDocGen.RemoveCommentHeader(text)

parameters

text  

NPLDocGen.PreProcRPCWrapperToFunction


pre processor

add a fake function in front of paraworld.CreateRPCWrapper() for documentation generation purposes.

syntax

function NPLDocGen.PreProcRPCWrapperToFunction(input)

parameters

input  

NPLDocGen.MakeValidMCMLWikiWords


post processor

This is a post processing function. To convert MCML tag in pe namespace to valid wiki words

syntax

function NPLDocGen.MakeValidMCMLWikiWords(input)

parameters

input such as pe:map-mark2d

NPLDocGen.MakeValidParaWorldAPIWikiWords

syntax

function NPLDocGen.MakeValidParaWorldAPIWikiWords(input)

parameters

input such as paraworld.auth.AuthUser
Topic revision: r1 - 2008-02-29 - LiXizhi
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback