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

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

• param input : such as pe:map-mark2d
• return __ :pe:map-mark2d

syntax

function NPLDocGen.MakeValidMCMLWikiWords(input)

parameters

input	such as pe:map-mark2d

NPLDocGen.MakeValidParaWorldAPIWikiWords

• param input : such as paraworld.auth.AuthUser
• return __ :paraworld.auth.AuthUser

syntax

function NPLDocGen.MakeValidParaWorldAPIWikiWords(input)

parameters

input	such as paraworld.auth.AuthUser