For those who don’t know, HeaderDoc (https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/HeaderDoc/intro/intro.html) is a source code documentation system with support for AppleScript. The version shipping with the current Xcode 5 is ok for commenting simple scripts, but it has a few bugs. Those bugs have been recently patched, and the patched version has greatly improved: for example, it can document nested scripts (scripts defined inside handlers). With the patched version I’ve been able to document fairly complex scripts. This is an example of documentation generated by HeaderDoc for an AppleScript script: http://lifepillar.com/ASUnit/.
We may expect that an updated HeaderDoc will ship with the next Xcode release. Until then, you may patch HeaderDoc yourself, as follows:
- Download HeaderDoc 8.9.14 from http://opensource.apple.com/release/developer-tools-46/.
- Download the diff files that you find here: http://www.darwin-development.org/headerdoc_patches/Xcode_5/.
- Put the diff files inside the headerdoc-8.9.14 folder.
- In Terminal.app, cd into headerdoc-8.9.14 and execute these commands:
After that, you may use headerDoc2HTML.pl and gatherHeaderDoc.pl inside headerdoc-8.9.14 instead of the system’s headerdoc2html and gatherheaderdoc, respectively.
There are not many solutions for documenting AppleScript source files: as far as I know, currently the only alternative to HeaderDoc is a hand-made comment parser (some have been posted to this forum in the past). So, it is very good news in my opinion that HeaderDoc is getting better and better!