A set of handlers for documenting handlers

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. :slight_smile:

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

A spinoff, I don’t remember all of the parameter labels, so this opens up a TextEdit document, with the labels within.

script showLabels
	set L 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"}
	set {tids, AppleScript's text item delimiters} to {AppleScript's text item delimiters, linefeed}
	set L to L as text
	set AppleScript's text item delimiters to tids
	do shell script "cat <<<" & quoted form of L & ">|/tmp/labels.txt ; open -ge /tmp/labels.txt "
end script
tell showLabels to run

Changed text item delimeters from " ," to ", " to pull off paremters in parenthesis correctly in the script in post #1. :o

Posted my version, so I have changed the Script Debugger document from 2 to 1! :0

The linefeed stopped working, so I have changed those to return.

The script didn’t take height for the given keyword. That is hereby fixed.

Hello.

I have changed the script, so that it now activates the previous app. when the script has run, the idea is that this is your editor of choice, so that you just run the script, and paste the documentation skeleton of the handler into your documentation.