Hello!
A small collection of handlers , that makes you able to select the “signature” of a handler, and produce documentation by it, works best with scripts that compiles. 
By “signature” I mean something like: makeMarkdownDocBlock(asHandler).
I use this by selecting the line containing the signature, to produce documentation for indidividual handlers as seen below, in a markdown document. The Markdown document gets processed into html by other scripts; I have aliases to the html documents in the infoLib folder of my Script Menu, so that when I wonder, I open up the html in Safari, and copies the full signature from there into some script I am working on.
This is kind of specifically made for Script Debugger, but should be easy to “port” to AppleScript Editor, Smile, and others.
The handlers are made so that I can select the header of a handler in say a script library, and then get a documentation block of the handle to clipbard, which I then can paste into my markdown document.
The markdown doc handler, should be equally or even easier to paste into another format.
Enjoy!
stripTrailingComment for anAsHeaderSignature
stripTrailingComment does: strip the trailing comment from an ASHandler signature
Returns:
The handler without any commens
Parameters:
anAsHeaderSignature
The “head” of the handler definition.
getHandlerData()
getHandlerData does: Collect the full signature of a handler, selected in a Script Debugger document, and delivers the full signature, the name of the handler, and the argument list, for further processing by a handler that turns this information into meaningful documentation.
Returns:
A list with { fullHandlerSignature, handlerName, argumentList }
Parameters:
None.
makeMarkdownDocBlock(asHandler)
makeMarkdownDocBlock does: creates a
Returns:
Parameters:
asHandler
A list with { fullHandlerSignature, handlerName, argumentList }
script asLibDoc
-- http://macscripter.net/viewtopic.php?pid=158192#p158192
-- Version 1.0.5 Line-endings!
-- © 2012 McUsr BSD 2.0 Please refer to this link: http://macscripter.net/edit.php?id=158191
on run
local handlerData
set handlerData to getHandlerData()
if handlerData is not null then
set the clipboard to "" as text # hopefully a fix for line-ending problems.
set the clipboard to makeMarkdownDocBlock(handlerData) as text
end if
# gets the data
# pastes formatted handler definition to clipboard.
tell application id "sevs"
set otherApp to name of item -1 of (every application process whose visible is true)
end tell
tell application otherApp to activate
end run
to makeMarkdownDocBlock(asHandler)
local twoLfs, theHeader, initial_comment, returnline, parameterline
set twoLfs to return & return
set theHeader to "## " & item 1 of asHandler & twoLfs -- the full signature
set initial_comment to item 2 of asHandler & " does: " & twoLfs
set returnline to "### Returns:" & twoLfs
set parameterline to "### Parameters: " & twoLfs
local argList
set argList to item 3 of asHandler
if argList = {} then
set parameterline to parameterline & "None." & twoLfs
else
repeat with anArg in item 3 of asHandler
local argline, theofs, theArg
set thOfs to offset of ":" in (contents of anArg)
if thOfs > 0 then
set theArg to text 1 thru (thOfs - 1) of contents of anArg
else
set theArg to contents of anArg
end if
set argline to "#### " & theArg & twoLfs
set parameterline to parameterline & argline
end repeat
end if
local theDocBlock
set theDocBlock to theHeader & initial_comment & returnline & parameterline
return theDocBlock as text
end makeMarkdownDocBlock
to getHandlerData()
tell application "Script Debugger 4.5"
set a to its document 1
set textSel to selection of a
try
set handlerKeyword to first word of textSel
on error
activate
display alert "Not handler signature."
return null
end try
if handlerKeyword is not in {"on", "to"} then
activate
display alert "Not handler signature."
return null
else
set textSel to text ((offset of handlerKeyword in textSel) + 3) thru -1 of textSel
# we remove the space as well
end if
set fullHandlerSignature to stripTrailingComment of me for textSel
if (offset of "*)" in fullHandlerSignature) is not 0 then
activate
display alert "bad bad handler signature"
return null
else
# time to split into parts, handler name and a list of its arguments.
local handlerName, parensStart, startArgList, endArgList, tids, parensStart
set parensStart to (offset of "(" in fullHandlerSignature)
# figure out the form of the handler: parens or label predicates
if parensStart is not 0 then -- parenthized arg list
set handlerName to text 1 thru (parensStart - 1) of fullHandlerSignature
set startArgList to parensStart + 1
set endArgList to (offset of ")" in fullHandlerSignature) - 1
set argList to text startArgList thru endArgList of fullHandlerSignature
if length of argList = 2 then
set argList to {}
else
set {tids, AppleScript's text item delimiters} to {AppleScript's text item delimiters, ", "}
set argList to text items of argList
set AppleScript's text item delimiters to tids
end if
else
local theLabelList
set theLabelList to {" about ", " above ", " against ", " apart from ", " around ", " aside from ", " at ", " below ", " beneath ", " beside ", " between ", " by ", " for ", " from ", " instead of ", " into ", " on ", " onto ", " out of ", " over ", " since ", " thru ", " through ", " under ", " given "}
# we are having the predicate thing
set startArgList to (offset of " " in fullHandlerSignature)
set endArgList to -1
set handlerName to text 1 thru (startArgList - 1) of fullHandlerSignature
set argList to text startArgList thru endArgList of fullHandlerSignature
considering white space
set {tids, AppleScript's text item delimiters} to {AppleScript's text item delimiters, theLabelList}
set argList to text items 2 thru -1 of argList
end considering
set AppleScript's text item delimiters to tids
end if
end if
end tell
return {fullHandlerSignature, handlerName, argList}
end getHandlerData
to stripTrailingComment for anAsHeaderSignature
# removes any comment at the end of a headerSignature
local commentOpeners, tids
set {commentOpeners, tids} to {{"#", "--", "(*"}, AppleScript's text item delimiters}
repeat with aComment in commentOpeners
set AppleScript's text item delimiters to contents of aComment
local theBits, nrBits
set theBits to text items of anAsHeaderSignature
set nrBits to length of theBits
if nrBits > 1 then
set anAsHeaderSignature to text item 1 of theBits as text
end if
end repeat
set AppleScript's text item delimiters to tids
repeat while text -1 of anAsHeaderSignature = space
set anAsHeaderSignature to text 1 thru -2 of anAsHeaderSignature
end repeat
return anAsHeaderSignature
end stripTrailingComment
end script
tell asLibDoc to run