Proposal for Documentation Comments for User Handlers

Script Debugger Feature Requests
#1

Script Debugger offers excellent support for handler AutoFill, unlike Apple’s Script Editor. Unfortunately, unlike many languages, AppleScript doesn’t have any standard form of documentation comments, so Script Debugger can’t provide more descriptive AutoFill information for things such as:

  • Handler description
  • Parameter descriptions / acceptable values
  • Return value
  • Preconditions
  • Other important notes

All of these would be very helpful to have at the call site, especially since there’s no way to quick jump to the handler definition when it’s in a Script Library.

Apple appears to have largely lost interest in AppleScript, but it remains the best way to accomplish a lot of tasks in macOS. Script Debugger therefore could set the de facto standard for documentation comments in AppleScript.

I don’t know the timeline for Script Debugger 9, but this could definitely be a headlining feature. AppleScript comments could be modelled after Swift’s Documentation Comments, which for AppleScript would look something like this:

(**
Handler description.

- Requires: Requirements.

- Parameters:
  - Identifier: Class - Description.

- Throws: Error information.

- Returns: Class - Return value.
*)

I had briefly alluded to something like this in a post a while back, but thought I would write up a formal feature request.

If there’s little appetite for really building out this feature, even just displaying a single free-formatted comment as “quick help” (and leaving comment style to the user) would still be very useful for people who have large script libraries of user handlers.

Anyway… thanks for reading!

General Discussion – Current State of ASObjC on Modern macOS
#2

This may be something you could do now, via an appleScript in the script menu.

Can you post an example of a script with handlers documented the way you think would work best? We could try to recreate it.

(FWIW, because of its nature appleScript requires minimal comments. I remember stories of when the NeXT engineers met with their Apple counterparts that they thought the actual appleScript commands were comments)

#3

Thanks Ed. I can post some examples of the non-trivial handler documentation comments I have in my script libraries. The format I’ve been using was a little more python-inspired, but wasn’t chosen with machine-parsing in mind, unfortunately.

replaceText(s, search_string, replacement_string)

(* (string OR list of strings, string OR list of strings, string OR list of strings) → string OR list of strings

Return a copy of s with all instances of search_string replaced with replacement_string. s may be either a string or a list of strings. Search_string may be a list containing multiple substrings to be replaced by replacement_string; if replacement_string is also a list of substrings, then each substring in search_string will be sequentially replaced with the corresponding substring in replacement_string.

Parameters:
s [string OR list of strings] : The string(s).
search_string [string OR list of strings] : The substring, or list of substrings, to be replaced.
replacement_string [string OR list of strings] : The substring, or list of substrings, to replace the search string(s).

Result:
[string OR list of strings] : A copy of s with the appropriate substitutions made. *)

trimString(s, trim_from, trim_to, mode)

(* (string, string OR integer, string OR integer, string) → string

Return a copy of s, sliced from trim_from to trim_to (which may be search strings or indices), modified according to the options in mode. The default mode is to return the largest possible match for the given search strings, and to drop the search strings in the return value.

The following options are available:
F - Return the first possible match for the search strings.
U - Return the last possible match for the search strings.
K - Keep both the left and right search strings from the return value (same as “LR”).
L - Keep the left search string in the return value.
R - Keep the right search string in the return value.
I - Inverse mode. Remove the centre of the string instead of the ends.
S - Strict mode. Return an empty string if either of the search strings are not found.

Parameters:
s [string] : The string.
trim_from [string OR integer] : The substring (or index) marking the start of the trimming.
trim_to [string OR integer] : The substring (or index) marking the end of the trimming.
mode [string] : A list of options.

Result:
[string] : A copy of s trimmed from trim_from to trim_to according to the options given in mode. *)

getUnicodeName(chars)

(* (string) → string

Return the Unicode character name for every character in chars, each on its own line.

Requires Python 3.

Parameters:
chars [string] : The string of Unicode characters.

Result:
[string] : The Unicode character name for every character in the string, separated by a linefeed. *)

getPath(file_specifier)

(* (file specifier) → string

Return the POSIX path of file_specifier, which may be a POSIX path (slash-delimited string), an HFS path (colon-delimited string), a file URL (POSIX file), an AppleScript alias, an AppleScript file reference, a Finder object, or a System Events object.

Parameters:
file_specifier [string OR file URL OR alias OR file OR “Finder” item OR “System Events” item] : A file object or path.

Result:
[string] : The POSIX path of file_specifier. *)

getModifierKeys()

(* () → record of booleans

Return a record of booleans indicating which modifier keys are currently pressed; the record’s keys are ‘command’, ‘control’, ‘option’, ‘shift’, ‘fn’, and ‘caps’. Note that ‘caps’ indicates whether Caps Lock is active, independent of whether the button is physically depressed.

The result contains the following properties:
command [boolean] : True if the command key is currently pressed.
control [boolean] : True if the control key is currently pressed.
option [boolean] : True if the option/alt key is currently pressed.
shift [boolean] : True if the shift key is currently pressed.
fn [boolean] : True if the fn key is currently pressed.
caps [boolean] : True if the caps lock key is currently pressed.

Parameters:
None.

Result:
[record of booleans] : A record indicating which modifier keys are currently pressed. *)

I could certainly make some kind of AppleScript that would pull these up, but it would require Script Debugger support to get Xcode-style quick help.