4 files changed, 126 insertions, 2 deletions
diff --git a/Framework/MASDictionaryTransformer.h b/Framework/MASDictionaryTransformer.h
index f0eb558..eced1bb 100644
--- a/Framework/MASDictionaryTransformer.h
+++ b/Framework/MASDictionaryTransformer.h
@@ -1,4 +1,19 @@
 extern NSString *const MASDictionaryTransformerName;
 
+/**
+    @brief Converts shortcuts for storage in user defaults.
+
+    User defaults can’t stored custom types directly, they have to
+    be serialized to @p NSData or some other supported type like an
+    @p NSDictionary. In Cocoa Bindings, the conversion can be done
+    using value transformers like this one.
+
+    There’s a built-in transformer (@p NSKeyedUnarchiveFromDataTransformerName)
+    that converts any @p NSCoding types to @p NSData, but with shortcuts
+    it makes sense to use a dictionary instead – the defaults look better
+    when inspected with the @p defaults command-line utility and the
+    format is compatible with an older sortcut library called Shortcut
+    Recorder.
+*/
 @interface MASDictionaryTransformer : NSValueTransformer
 @end
diff --git a/Framework/MASShortcut.h b/Framework/MASShortcut.h
index 2168952..3e1bedf 100644
--- a/Framework/MASShortcut.h
+++ b/Framework/MASShortcut.h
@@ -1,18 +1,70 @@
 #import "MASKeyCodes.h"
 
-@interface MASShortcut : NSObject <NSSecureCoding>
+/**
+    @brief A model class to hold a key combination.
 
+    This class just represents a combination of keys. It does not care if
+    the combination is valid or can be used as a hotkey, it doesn’t watch
+    the input system for the shortcut appearance, nor it does access user
+    defaults.
+*/
+@interface MASShortcut : NSObject <NSSecureCoding, NSCopying>
+
+/**
+    @brief The virtual key code for the keyboard key.
+
+    @Hardware independent, same as in NSEvent. Events.h in the HIToolbox
+    framework for a complete list, or Command-click this symbol: kVK_ANSI_A.
+*/
 @property (nonatomic, readonly) NSUInteger keyCode;
+
+/**
+    @brief Cocoa keyboard modifier flags.
+
+    Same as in NSEvent: NSCommandKeyMask, NSAlternateKeyMask, etc.
+*/
 @property (nonatomic, readonly) NSUInteger modifierFlags;
+
+/**
+    @brief Same as @p keyCode, just a different type.
+*/
 @property (nonatomic, readonly) UInt32 carbonKeyCode;
+
+/**
+    @brief Carbon modifier flags.
+
+    A bit sum of @p cmdKey, @p optionKey, etc.
+*/
 @property (nonatomic, readonly) UInt32 carbonFlags;
+
+/**
+    @brief A string representing the “key” part of a shortcut, like the “5” in “⌘5”.
+*/
 @property (nonatomic, readonly) NSString *keyCodeString;
+
+/**
+    @brief A key-code string used in key equivalent matching.
+
+    For precise meaning of “key equivalents” see the @p keyEquivalent
+    property of @p NSMenuItem. Here the string is used to support shortcut
+    validation (“is the shortcut already taken in this menu?”) and
+    for display in @p NSMenu.
+*/
 @property (nonatomic, readonly) NSString *keyCodeStringForKeyEquivalent;
+
+/**
+    @brief A string representing the shortcut modifiers, like the “⌘” in “⌘5”.
+*/
 @property (nonatomic, readonly) NSString *modifierFlagsString;
 
 - (instancetype)initWithKeyCode:(NSUInteger)code modifierFlags:(NSUInteger)flags;
-
 + (instancetype)shortcutWithKeyCode:(NSUInteger)code modifierFlags:(NSUInteger)flags;
+
+/**
+    @brief Creates a new shortcut from an NSEvent object.
+
+    This is just a convenience initializer that reads the key code and modifiers from an NSEvent.
+*/
 + (instancetype)shortcutWithEvent:(NSEvent *)anEvent;
 
 @end
diff --git a/Framework/MASShortcutBinder.h b/Framework/MASShortcutBinder.h
index 98e01c7..1592e90 100644
--- a/Framework/MASShortcutBinder.h
+++ b/Framework/MASShortcutBinder.h
@@ -1,13 +1,57 @@
 #import "MASShortcutMonitor.h"
 
+/**
+    @brief Binds actions to user defaults keys.
+
+    If you store shortcuts in user defaults (for example by binding
+    a @p MASShortcutView to user defaults), you can use this class to
+    connect an action directly to a user defaults key. If the shortcut
+    stored under the key changes, the action will get automatically
+    updated to the new one.
+
+    This class is mostly a wrapper around a @p MASShortcutMonitor. It
+    watches the changes in user defaults and updates the shortcut monitor
+    accordingly with the new shortcuts.
+*/
 @interface MASShortcutBinder : NSObject
 
+/**
+    @brief A convenience shared instance.
+
+    You may use it so that you don’t have to manage an instance by hand,
+    but it’s perfectly fine to allocate and use a separate instance instead.
+*/
 + (instancetype) sharedBinder;
 
+/**
+    @brief The underlying shortcut monitor.
+*/
 @property(strong) MASShortcutMonitor *shortcutMonitor;
+
+/**
+    @brief Binding options customizing the access to user defaults.
+
+    As an example, you can use @p NSValueTransformerNameBindingOption to customize
+    the storage format used for the shortcuts. By default the shortcuts are converted
+    from @p NSData (@p NSKeyedUnarchiveFromDataTransformerName). Note that if the
+    binder is to work with @p MASShortcutView, both object have to use the same storage
+    format.
+*/
 @property(copy) NSDictionary *bindingOptions;
 
+/**
+    @brief Binds given action to a shortcut stored under the given defaults key.
+
+    In other words, no matter what shortcut you store under the given key,
+    pressing it will always trigger the given action.
+*/
 - (void) bindShortcutWithDefaultsKey: (NSString*) defaultsKeyName toAction: (dispatch_block_t) action;
+
+/**
+    @brief Disconnect the binding between user defaults and action.
+
+    In other words, the shortcut stored under the given key will no longer trigger an action.
+*/
 - (void) breakBindingWithDefaultsKey: (NSString*) defaultsKeyName;
 
 /**
diff --git a/Framework/MASShortcutMonitor.h b/Framework/MASShortcutMonitor.h
index 5c0daa2..609686a 100644
--- a/Framework/MASShortcutMonitor.h
+++ b/Framework/MASShortcutMonitor.h
@@ -1,10 +1,23 @@
 #import "MASShortcut.h"
 
+/**
+    @brief Executes action when a shortcut is pressed.
+
+    There can only be one instance of this class, otherwise things
+    will probably not work. (There’s a Carbon event handler inside
+    and there can only be one Carbon event handler of a given type.)
+*/
 @interface MASShortcutMonitor : NSObject
 
 - (instancetype) init __unavailable;
 + (instancetype) sharedMonitor;
 
+/**
+    @brief Register a shortcut along with an action.
+
+    Attempting to insert an already registered shortcut probably won’t work.
+    It may burn your house or cut your fingers. You have been warned.
+*/
 - (void) registerShortcut: (MASShortcut*) shortcut withAction: (dispatch_block_t) action;
 - (BOOL) isShortcutRegistered: (MASShortcut*) shortcut;