While perusing Xcode’s AppleScript scripting dictionary, I was surprised to discover a rather robust “example code” section included right there among the usually spartan reference of the app’s scriptable entities:

Curious to learn more, I used a relatively little-known trick for examining the raw source code of a scripting dictionary. Simply click and drag from Script Editor’s document proxy icon, into a text editor such as TextEdit, Xcode, or BBEdit:

This trick is especially handy because even if the app in question doesn’t have a standard scripting definition (.sdef) file representing its interface, Script Editor will generate one dynamically for you. It’s a quick-and-dirty way to learn how specific outcomes are achieved, and how you might incorporate similar features in your own app’s scripting definition file. In this case, I discovered a new (to me) “documentation” element in the file:

I was not aware of the feature until a few weeks ago, but apparently it’s been there since at least Mac OS 10.5. Script Debugger supports it, too! You can read more about the “documentation” element by invoking “man 5 sdef” from the Terminal:

When an element needs more exposition than a simple ‘description’ attribute can provide, use a documentation element. A documentation element may contain any number of html elements, which contain text that will be displayed at that point in the dictionary.

Given the sad state of support for AppleScript by Apple, and the continued low level of adoption by 3rd-party developers, a feature like this will probably never be widely used or celebrated. But at least in FastScripts 3.2.4, which I just released this morning, I’m now taking advantage of it:

If you’re among the few remaining Mac developers who is investing time and effort into your AppleScript scripting definitions, hopefully you’ll find this feature useful!