script "revDocsParser"

/*

Tests the features of the inline documentation parser & display

Synonyms: none

Associations: stack, revIdeDocsLibrary

pArrayParam (array): An array parameter

{ key : "key1"

value: "value1"

key : "key2"

value (array) : A sub-array

{ key (integer) : an integer key

value (string) : the description of the value at this index }

optional key : an optional key

value (string): the value associated with this optional key }

pEnumParam (enum): An enum parameter

-"option 1" : description of option 1

- option 2 : description of option 2

- option 3 : description of option 3

pOptionalParam (optional integer): An integer parameter

pParam: A param afterward with no space

The result: Sets the result to empty

Returns (string): Description of string

Example:

// Some inline docs for myHandler...

on myHandler pParam

// do something

end myHandler

// Some inline docs for myOtherHandler...

on myOtherHandler

// do something other

end myOtherHandler

Description:

Should have examples of *every* type of docs element in order to **make sure** they display correctly.

Can have some *markdown* in it:

* List

* Of

* Things

References:

myFavourite.command,ANOther.function

Tags: documentation, meta

*/

function revDocsInlineDocsParsingTest pArrayParam, pEnumParam, pOptionalParam, pParam

return empty

end revDocsInlineDocsParsingTest

function revDocsGetBuiltinModuleList pModuleInterfacePath, pRepoPath

local tModulePath, tEngine, tScript, tListA

put pModuleInterfacePath into tModulePath

put pRepoPath & slash & "engine" & slash & "src" into tEngine

put pRepoPath & slash & "libscript" & slash & "src" into tScript

local tInstalled

put files(tModulePath) into tInstalled

filter tInstalled with "*.lci"

local tSourcePaths

put tScript into tSourcePaths[1]

put tEngine into tSourcePaths[2]

local tCount

put 1 into tCount

set the itemdelimiter to "."

local tFiles

repeat for each element tElement in tSourcePaths

local tDocsA

put files(tElement) into tFiles

filter tFiles with regex pattern ".*(\.(mlc|lcb))+"

# Check to see if the corresponding interface file exists so that we

# don't add anything to the dictionary that isn't actually there.

repeat for each line tFile in tFiles

local tInterfaceFile

put "com.livecode." & tFile into tInterfaceFile

put "lci" into item -1 of tInterfaceFile

if replaceText(tInterfaceFile, "-", "") is not among the lines of tInstalled then next repeat

put true into tListA[tElement & slash & tFile]

end repeat

end repeat

put files(pRepoPath & slash & "docs" & slash & "builder") into tFiles

filter tFiles with "*.lcdoc"

repeat for each line tFile in tFiles

put true into tListA[pRepoPath & slash & "docs" & slash & "builder" & slash & tFile]

end repeat

return the keys of tListA

end revDocsGetBuiltinModuleList

function revDocsGenerateDocsFilesFromBuiltIn pModuleInterfacePath, pRepoPath

local tModulePath, tEngine, tScript

put pModuleInterfacePath into tModulePath

put pRepoPath & slash & "engine" & slash & "src" into tEngine

put pRepoPath & slash & "libscript" & slash & "src" into tScript

local tInstalled

put files(tModulePath) into tInstalled

filter tInstalled with "*.lci"

local tSourcePaths

put tScript into tSourcePaths[1]

put tEngine into tSourcePaths[2]

local tCount

put 1 into tCount

set the itemdelimiter to "."

local tFiles

repeat for each element tElement in tSourcePaths

local tDocsA

put files(tElement) into tFiles

filter tFiles with regex pattern ".*(\.(mlc|lcb))+"

# Check to see if the corresponding interface file exists so that we

# don't add anything to the dictionary that isn't actually there.

repeat for each line tFile in tFiles

local tInterfaceFile

put "com.livecode." & tFile into tInterfaceFile

put "lci" into item -1 of tInterfaceFile

if replaceText(tInterfaceFile, "-", "") is not among the lines of tInstalled then next repeat

get revDocsGenerateDocsFileFromModularFile(tFile)

if it is not empty then

put it into tDocsA[tCount]

add 1 to tCount

end if

end repeat

end repeat

put files(pRepoPath & slash & "docs" & slash & "builder") into tFiles

filter tFiles with "*.lcdoc"

repeat for each line tFile in tFiles

local tContents

put revDocsUtf8FileContents(tFile) into tContents

if tContents is not empty then

put tContents into tDocsA[tCount]

add 1 to tCount

end if

end repeat

return tDocsA

end revDocsGenerateDocsFilesFromBuiltIn

/*

Summary: Formats a libraries array as JSON.

pLibrariesA (array): A libraries array is a numerically keyed array of library arrays.

Description:

Each element of the numerically keyed <pLibrariesA> is a library array.

The latter consists of three keys, "name", "author", and "doc". The first two of these are strings.

The third is an array. The "doc" subarray is numerically keyed.

Each element of it represents the documentation for a handler contained in the library.

There are a number of ways of creating a library array:

* <revDocsParseDirectoryToLibraryArray> creates a library array from all of the (non-inline) docs entries of a given type in a directory

* <revDocsParseDictionaryToLibraryArray> creates the dictionary library array

*/

function revDocsFormatLibrariesArrayAsJSON pLibrariesA

local tJSON

repeat for each element tLibraryA in pLibrariesA

get revDocsFormatLibraryArrayAsJSON(tLibraryA)

if it is not empty then

put it & comma after tJSON

end if

end repeat

delete the last char of tJSON

return tJSON

end revDocsFormatLibrariesArrayAsJSON

/*

Summary: Create a library array with all the docs data from the specified directory

Parameters:

pLibraryName (string): The name of the library

pAuthor(string): The author of the library

pRootDir(string): The root directory to search for files

pType (enum): The type of docs to parse

- "modular": This will take any inline docs in .lcb files as well as all standard .lcdoc files in the directory

- "script": This will take any inline docs in .livecode files as well as all standard .lcdoc files in the directory

- "dictionary": This will take the standard .lcdoc files in the directory and parse as dicitonary entries

Returns(array): An array consisting of all the parsed docs data

{ key: "name"

value(string): the name of the library

key: "author"

value(string): the author of the library

key: "doc"

value(array): an array, with one key per handler or syntax element

{ key(string): the name of the handler or syntax element

value(array): an array of all the docs elements for this handler or piece of syntax

}

}

*/

function revDocsParseDirectoryToLibraryArray pLibraryName, pAuthor, pRootDir, pType, pRecursive

local tLibraryA

if there is a folder pRootDir then

put pLibraryName into tLibraryA["name"]

put pAuthor into tLibraryA["author"]

put pType into tLibraryA["type"]

if pType is "dictionary" then

put revDocsParseDictionaryToLibraryArray(pRootDir) into tLibraryA["doc"]

else

put __revDocsParseDirectoryToLibraryArray(pType, pRootDir, pRecursive) into tLibraryA["doc"]

end if

end if

if tLibraryA["doc"] is not empty then

return tLibraryA

end if

return empty

end revDocsParseDirectoryToLibraryArray

/*

Summary: Parses the current directory into a library array.

pRootDir (string): The path to the root directory of the dictionary

*/

function revDocsParseDictionaryToLibraryArray pRootDir

if there is not a folder pRootDir then

return empty

end if

# Get the list of canonical glossary entries

local tGlossaryA

put revDocsCollectGlossarySynonyms(pRootDir) into tGlossaryA

local tDictionaryRoot, tGlossaryRoot

put pRootDir & slash & "dictionary" into tDictionaryRoot

put pRootDir & slash & "glossary" into tGlossaryRoot

local tCount

put 1 into tCount

local tText, tLibraryA, tParsedA

repeat for each item tRoot in (tDictionaryRoot & "," & tGlossaryRoot)

repeat for each line tLine in folders(tRoot)

if tLine is ".." then next repeat

get files(tRoot & slash & tLine)

filter it with "*.lcdoc"

repeat for each line tFile in it

if the environment is "development" and \

not revTestEnvironment() then

wait 0 with messages

end if

local tFullPath

put tRoot & slash & tLine & slash & tFile into tFullPath

put revDocsUtf8FileContents(tFullPath) into tText

put revDocsParseDocText(tText, tFullPath) into tParsedA

put tParsedA["doc"][1] into tLibraryA[tCount]

add 1 to tCount

end repeat

end repeat

end repeat

return tLibraryA

end revDocsParseDictionaryToLibraryArray

/*

Summary: Takes a .lcdoc file and formats it as a JSON array.

*/

function revDocsFormatAPIAsJSON pLibraryName, pAuthor, pAPIFile

# Get the data

local tText

put revDocsUtf8FileContents(pAPIFile) into tText

return revDocsFormatDocTextAsJSON(pAPIFile, tText, pLibraryName, pAuthor)

end revDocsFormatAPIAsJSON

/*

Summary: Takes a .lcdoc file and parses it into a library array.

*/

function revDocsParseFileToArray pFile, pType, @xCount, @xLibraryA

# Get the data

local tText

put revDocsUtf8FileContents(pFile) into tText

return revDocsParseFileContentsToArray(pFile, tText, pType, xCount, xLibraryA)

end revDocsParseFileToArray

function revDocsParseFileContentsToArray pFile, pText, pType, @xCount, @xLibraryA

# Extract and parse the comment blocks

local tParsedA

switch pType

case "modular"

put revDocsParseDocText(pText, pFile) into tParsedA

break

case "script"

local tBlocksA

put revDocsParseScriptDocs(pText) into tBlocksA

put revDocsParseDocBlocks(tBlocksA, pFIle) into tParsedA

break

end switch

# Add to the library array

repeat for each key tEntry in tParsedA

put tParsedA[tEntry] into xLibraryA[xCount]

put tEntry into xLibraryA[xCount]["name"]

add 1 to xCount

end repeat

return empty

end revDocsParseFileContentsToArray

function revDocsGenerateDocsFilesFromModularDirectory pDir

local tFiles

put files(pDir) into tFiles

filter tFiles with regex pattern ".*(\.(mlc|lcb))+"

local tDocsA, tCount

put 1 into tCount

repeat for each line tFile in tFiles

get revDocsGenerateDocsFileFromModularFile(tFile)

if it is not empty then

put it into tDocsA[tCount]

add 1 to tCount

end if

end repeat

return tDocsA

end revDocsGenerateDocsFilesFromModularDirectory

/*

Summary: Extracts the inline docs from a .lcb file

pFile: The path to the .lcb file to extract docs from

Returns (string): A string consisting of all the docs for the syntax and handlers present in the .lcb file

Description:

<revDocsGenerateDocsFileFromModularFile> is used when packaging a widget to create its API documentation.

It generates the Library and Type elements from the declaration in the <pFile> (either widget or library), and extracts

the comment block that precedes any initial declaration for use as the library-level Description element.

It then extracts the comment blocks that precede syntax and handler definitions in <pFile>, and generates the

Name, Type, Syntax, and Associated elements for each entry, as well as the parameter types.

Tags: Package building

*/

function revDocsGenerateDocsFileFromModularFile pFile

local tContents

put revDocsUtf8FileContents(pFile) into tContents

return revDocsGenerateDocsFileFromModular(tContents, pFile)

end revDocsGenerateDocsFileFromModularFile

/*

Convert inline docs to the standard format (that can be parsed without code blocks)

*/

function revDocsGenerateDocsFileFromModular pText, pFilename

return revDocsGenerateDocsFileFromText(pText, pFilename)

end revDocsGenerateDocsFileFromModular

function revDocsGenerateDocsFileFromText pText, pSource

local tEntryType

put empty into tEntryType

local tInComment, tInEntry, tEntryEnded

put false into tInComment

put false into tInEntry

local tFirstWord, tEntryData

local tComment, tData

local tHandlerData, tPhraseData

local tLibraryData, tAPIData

revDocsExtractDocBlocks pText, pSource, tAPIData, tLibraryData

# Allow inline module description as valid docs

if tAPIData is empty then

logWarning "No handlers documented", pSource

end if

if tLibraryData["name"] is empty then

logError "No extension name found", pSource

end if

local tOutput

put revDocsFormatInlineComments(tLibraryData, true) into tOutput

if tOutput is empty then

logWarning "Invalid library-level docs", pSource

end if

repeat for each key tKey in tAPIData

local tFormatted

put revDocsFormatInlineComments(tAPIData[tKey], false) into tFormatted

if tFormatted is empty then

logWarning "No docs for element" && tKey, pSource

else

put tFormatted & return & return after tOutput

end if

end repeat

return tOutput

end revDocsGenerateDocsFileFromText

##################################################

#

# PARSING UTILITIES

#

##################################################

/*

Extracts the comment blocks that live in between functions which contain the documentation for those functions

pText: The script to extract comment blocks from

pSource : The source of the script (either a filename or an object id)

Returns (array) : An array containing the details for the comment blocks associated with each api entry

*/

on revDocsExtractDocBlocks pText, pSource, @rAPIData, @rLibraryData

local tEntryType

put empty into tEntryType

local tInComment, tInEntry, tEntryEnded

put false into tInComment

put false into tInEntry

local tFirstWord, tEntryData, tTrimLine

local tComment, tData

local tHandlerData, tPhraseData

local tLibraryData, tAPIData

# Keep track of if this is a widget module or not

local tIsWidget

put false into tIsWidget

# If the source is an object, then we are parsing script

local tIsScript

put there is a pSource into tIsScript

local tIsLCIDL = false

repeat for each line tLine in pText

# Check to see if this is the start of a handler / syntax or a block of comments

put word 1 of tLine into tFirstWord

# By default, the entry doesn't end on this line

put false into tEntryEnded

# If we are neither in a comment block or in handler / syntax then

if not tInComment and not tInEntry then

# In almost all cases, we will be in a new entry

put true into tInEntry

switch tFirstWord

case "external"

put true into tIsLCIDL

put "library" into tEntryData["type"]

put word 2 to -1 of tLine into tEntryData["name"]

put false into tInEntry

put true into tEntryData["need_docs"]

break

case "module"

case "library"

put tFirstWord into tEntryData["type"]

put word 2 to -1 of tLine into tEntryData["name"]

put true into tEntryEnded

put true into tEntryData["need_docs"]

break

case "widget"

put true into tIsWidget

put "widget" into tEntryData["type"]

put word 2 to -1 of tLine into tEntryData["name"]

put true into tEntryEnded

put true into tEntryData["need_docs"]

break

case "handler"

put "handler" into tEntryData["type"]

# Handler is private by default, so don't document

put true into tEntryData["private"]

break

case "private"

if word 2 of tLine is "handler" then

# Don't document private handler

put true into tEntryData["private"]

# eat the word 'private'

put word 2 to -1 of tLine into tLine

else

put false into tInEntry

end if

break

case "public"

if word 2 of tLine is "handler" then

put "handler" into tEntryData["type"]

# eat the word 'public'

put word 2 to -1 of tLine into tLine

put token 2 of tLine into tEntryData["name"]

# If we have a widget, then public handlers are not in the message path and so don't need docs.

put not tIsWidget into tEntryData["need_docs"]

else

put true into tEntryData["private"]

if word 2 of tLine is "foreign" then

if word 3 of tLine is "handler" then

put "handler" into tEntryData["type"]

else if word 3 of tLine is "type" then

put "type" into tEntryData["type"]

end if

# eat the words 'public foreign'

put word 3 to -1 of tLine into tLine

put true into tEntryEnded

end if

end if

break

case "syntax"

put word 2 of tLine into tEntryData["name"]

if word 4 of tLine is "phrase" then

put "phrase" into tEntryData["type"]

else

put "syntax" into tEntryData["type"]

put true into tEntryData["need_docs"]

end if

break

case "property"

put word 2 of tLine into tEntryData["name"]

put "property" into tEntryData["type"]

# Properties are one-liners

put true into tEntryEnded

put true into tEntryData["need_docs"]

break

case "on"

if tIsLCIDL then

put false into tInEntry

break

end if

put "command" into tEntryData["type"]

put word 2 of tLine into tEntryData["name"]

put false into tEntryData["need_docs"]

break

case "tail"

if not tIsLCIDL then

put false into tInEntry

break

end if

-- eat tail in lcidl

put word 2 of tLine into tFirstWord

put word 2 to -1 of tLine into tLine

case "command"

case "function"

if tFirstWord is "function" then

put "function" into tEntryData["type"]

else

put "command" into tEntryData["type"]

end if

put word 2 of tLine into tEntryData["name"]

put true into tEntryData["need_docs"]

break

default

# This is not a new entry

put false into tInEntry

# Check if this is a new comment block

if tFirstWord begins with "/**" and \

not (tFirstWord begins with "/**/") then

# If this is script, and this is an initial block of comments,

# then treat as the library description

if tIsScript and tAPIData is empty and tComment is not empty then

put "library" into tLibraryData["type"]

put tComment into tLibraryData["comments"]

put the short name of pSource into tLibraryData["name"]

end if

if tIsLCIDL and tAPIData is empty and tComment is not empty then

put tEntryData into tLibraryData

put tComment into tLibraryData["comments"]

end if

# Discard any previous comments

put empty into tComment

local tCommentOffset

put true into tInComment

put offset("/**", tLine) into tCommentOffset

put char (tCommentOffset + 3) to -1 of tLine into tLine

# If there's nothing else on this line, don't add it.

if word 1 of tLine is empty then next repeat

end if

break

end switch

end if

# If we're in comments check to see if this is the end of a block of comments

if tInComment then

if word -1 of tLine ends with "*/" then

put false into tInComment

put offset("*/", tLine) into tCommentOffset

delete char tCommentOffset to -1 of tLine

# Remove another star if this is a double-star comment closer

if char -1 of tLine is "*" then

delete char -1 of tLine

end if

if tIsLCIDL then

put false into tInEntry

end if

# If there's nothing else on this line, don't add it.

if word 1 of tLine is empty then

next repeat

end if

else if tComment is empty and tFirstWord is empty then

next repeat

end if

put tLine & return after tComment

next repeat

end if

# If we are in an entry, add the line to the current data

if tInEntry then

# handle line continuations

if char -2 of tData is "\" then

delete char -2 to -1 of tData

# ignore empty lines

else if tFirstWord is empty then

if tIsLCIDL then

put true into tEntryEnded

else

next repeat

end if

else if tFirstWord is "end" then

put true into tEntryEnded

end if

# continuation character can have spaces afterwards [[Bug 19927]]

# trim trailing spaces before adding

if matchText(tLine, "^(.*\\)\s*$", tTrimLine) then

put tTrimLine & return after tData

else

put tLine & return after tData

end if

end if

# If the entry is ended, convert all the collected data to a structured array

if tEntryEnded then

# Extract data from the syntax / handler if comments are not empty

if tComment is not empty then

switch tEntryData["type"]

case "library"

case "widget"

case "module"

put tComment into tEntryData["comments"]

put tEntryData into tLibraryData

break

case "handler"

revDocsParseHandler line 1 of tData, tHandlerData

revDocsUpdateDocBlocks true, "handler", line 1 of tData, tComment, tAPIData

break

case "function"

case "command"

if tIsLCIDL then

revDocsUpdateDocBlocksForLCIDL tEntryData["name"], tEntryData["type"], tData, tComment, tAPIData

else

revDocsUpdateDocBlocks false, tEntryData["type"], line 1 of tData, tComment, tAPIData

end if

break

case "type"

break

case "phrase"

put tData into tPhraseData[word 2 of tData]

break

case "syntax"

revDocsUpdateModularSyntaxDocBlocks tData, tComment, tHandlerData, tPhraseData, tAPIData

break

case "property"

revDocsUpdateDocBlocksForProperty tData, tComment, tAPIData

break

end switch

else

if tEntryData["need_docs"] then

logError "Required documentation not found for" && tEntryData["type"] && tEntryData["name"], pSource

end if

end if

put empty into tEntryData

put empty into tComment

put empty into tData

put false into tInEntry

end if

end repeat

put tAPIData into rAPIData

put tLibraryData into rLibraryData

end revDocsExtractDocBlocks

private command log pOutput

write pOutput & return to stdout

end log

private command logError pError, pFilename

log pFilename & ":" && "error:" && pError

end logError

private command logWarning pWarning, pFilename

log pFilename & ":" && "warning:" && pWarning

end logWarning

private function extensionsFromType pType

switch pType

case "module"

return ".*\.(lcb|lcdoc)"

case "script"

return ".*\.(livecode|lcdoc)"

case "dictionary"

return ".*\.lcdoc"

end switch

end extensionsFromType

private function __revDocsParseDirectoryToLibraryArray pType, pRootDir, pRecursive

if there is not a folder pRootDir then

return empty

end if

local tFiles, tExtensionRegex

put extensionsFromType(pType) into tExtensionRegex

put files(pRootDir) into tFiles

filter tFiles with regex pattern tExtensionRegex

local tCount

put 1 into tCount

local tLibraryA

if tFiles is not empty then

repeat for each line tFile in tFiles

revDocsParseFileToArray(tFile, pType, tCount, tLibraryA)

end repeat

end if

if pRecursive then

local tSubDirA

repeat for each line tLine in the folders

if tLine is ".." then

next repeat

end if

put __revDocsParseDirectoryToLibraryArray(pType, pRootDir & slash & tLine, pRecursive) into tSubDirA

repeat for each key tEntry in tSubDirA

put tSubDirA[tEntry] into tLibraryA[tCount]

add 1 to tCount

end repeat

end repeat

end if

return tLibraryA

end __revDocsParseDirectoryToLibraryArray

function revDocsFormatInlineComments pDataA, pIsLibrary

local tComment

put pDataA["comments"] into tComment

local tElementsA

put revDocsExtractElements(tComment) into tElementsA

local tEntriesA

put revDocsGroupElements(tElementsA) into tEntriesA

# If tEntries is empty, there was an error (docs empty, or no Name element)

if tEntriesA is empty then

return empty

end if

local tEntryA, tElementA, tElement

local tHasA

local tParamsFound

put false into tParamsFound

local tDocData

local tStart, tEnd

put 1 into tStart

put the number of elements in tEntriesA into tEnd

if tEntriesA[0] is not empty then

subtract 1 from tStart

subtract 1 from tEnd

end if

local tName, tType, tSyntax, tEntryDoc

repeat with x = tStart to tEnd

put empty into tHasA

put empty into tEntryDoc

put empty into tSyntax

put tEntriesA[x] into tEntryA

repeat with y = 1 to the number of elements in tEntryA["elements"]

put tEntryA["elements"][y] into tElementA

put tElementA["name"] into tElement

put true into tHasA[tElement]

if tElement is "Name" then

put tElementA["content"] into tName

next repeat

else if tElement is "Type" then

put tElementA["content"] into tType

next repeat

else if tElement is "Syntax" then

put tElementA["content"] into tSyntax[the number of elements of tSyntax + 1]

next repeat

end if

if tElement is "References" then

repeat for each element tPhrase in pDataA["phrases"]

put comma & tPhrase & "(phrase)" after tElementA["content"]

end repeat

end if

if tElement is "output" then

put "Returns" into tElementA["name"]

end if

if tElementA["name"] is "Returns" then

if tElementA["type"] is empty then

get pDataA["variants"][1]["return value"]["type"]

if it is not empty then

put it into tElementA["type"]

end if

end if

else if tElement is "The result" then

if tElementA["type"] is empty then

get pDataA["variants"][1]["the result"]["type"]

if it is not empty then

put it into tElementA["type"]

end if

end if

else

repeat for each element tVariant in pDataA["variants"]

repeat for each element tParam in tVariant

if tParam["name"] is tElement then

if not tParamsFound then

put "Parameters:" & return after tEntryDoc

put true into tParamsFound

end if

if tElementA["type"] is empty then

# add the param details if they were not included

if pDataA["phrases"][tElement] is not empty then

put "<" & word 1 to -1 of pDataA["phrases"][tElement] & ">" into tElementA["type"]

else if tParam["type"] is not empty then

put tParam["type"] into tElementA["type"]

end if

end if

if tParam["mode"] is not "in" then

put tParam["mode"] & " " before tElementA["type"]

end if

end if

end repeat

end repeat

end if

# Now output back to the doc data

put tElementA["name"] into tElement

if tElementA["type"] is not empty then

put tElement & "(" & tElementA["type"] & "):" && tElementA["content"] & return after tEntryDoc

else

if the number of lines in tElementA["content"] > 1 then

local tDeleteTab

put false into tDeleteTab

put tElement & ":" & return after tEntryDoc

repeat for each line tLine in tElementA["content"]

if line 1 of tElementA["content"] begins with tab then

put true into tDeleteTab

end if

if tDeleteTab and tLine begins with tab then

delete char 1 of tLine

end if

put tLine & return after tEntryDoc

end repeat

else

put tElement & ":" && tElementA["content"] & return after tEntryDoc

end if

end if

put return after tEntryDoc

end repeat

if tHasA["Syntax"] is not true then

put pDataA["syntax"] into tSyntax

end if

repeat with z = 1 to the number of elements in tSyntax

put "Syntax:" && tSyntax[z] & return & return before tEntryDoc

end repeat

if tHasA["Type"] is not true then

put pDataA["type"] into tType

end if

put "Type:" && tType & return & return before tEntryDoc

if tHasA["Name"] is not true then

put pDataA["name"] into tName

end if

if pIsLibrary and x = 0 then

put "Library:" && tName & return & return before tEntryDoc

else

put "Name:" && tName & return & return before tEntryDoc

end if

if tHasA["Parameters"] is not true and pDataA["params"] is an array then

put "Parameters:" & return after tEntryDoc

repeat with tParam = 1 to the number of elements of pDataA["params"]

put pDataA["params"][tParam]["name"] after tEntryDoc

if pDataA["params"][tParam]["type"] is not empty then

put " (" & pDataA["params"][tParam]["type"] & ")" after tEntryDoc

end if

put ":" & return & pDataA["params"][tParam]["description"] & return & return after tEntryDoc

end repeat

end if

repeat for each item tKey in "The result,Returns,it"

if tHasA[tKey] is not true and pDataA[tKey] is an array then

put tKey after tEntryDoc

if pDataA[tKey]["type"] is not empty then

put " (" & pDataA[tKey]["type"] & ")" after tEntryDoc

end if

put ":" & return & pDataA[tKey]["description"] & return & return after tEntryDoc

end if

end repeat

if tHasA["References"] is not true then

if pDataA["phrases"] is not empty then

put "References: " after tEntryDoc

repeat for each element tElement in pDataA["phrases"]

put tElement & "(phrase)" & comma after tEntryDoc

end repeat

delete the last char of tEntryDoc

put return & return after tEntryDoc

end if

end if

put tEntryDoc after tDocData

end repeat

return tDocData

end revDocsFormatInlineComments

function revDocsCollectGlossarySynonyms pRoot

local tGlossaryA, tText, tName, tSynonyms

local tFolders

put folders(pRoot & slash & "glossary") into tFolders

repeat for each line tLine in tFolders

if tLine is ".." then next repeat

get files(pRoot & slash & "glossary" & slash & tLine)

filter it with "*.lcdoc"

if it is not empty then

repeat for each line tFile in it

if tFile begins with "." then next repeat

local tFullPath

put pRoot & slash & "glossary" & slash & \

tLine & slash & tFile into tFullPath

put revDocsUtf8FileContents(tFullPath) into tText

get lineOffset("Name:", tText)

put word 2 to -1 of line it of tText into tName

if tName is empty then

next repeat

end if

get lineOffset("Synonyms:", tText)

put word 2 to -1 of line it of tText into tSynonyms

if tSynonyms is empty then

next repeat

end if

repeat for each item tItem in tSynonyms

put tName into tGlossaryA[tItem]

end repeat

end repeat

end if

end repeat

return tGlossaryA

end revDocsCollectGlossarySynonyms

private function __elementRegex

# Regex used to determine if this line starts a new element

# Matched substrings are element name, (optional) param type, same line element content

return "^ *([tT]he [rR]esult|\w+) *(?:\(( *(?:optional |in |out |inout )?<?\w*>?) *\))? *: *(.*)"

end __elementRegex

private function __arrayElementRegex

# Regex used to extract sub-array elements

# Essentially the same as the element regex except quotation marks are allowed

# as keys can obviously be string literals.

return "^ *([\w" & quote & "]+) *(?:\(( *(?:optional |in |out |inout )?<?\w*>?) *\))? *: *(.*)"

end __arrayElementRegex