From 66f3b1df452acaff91146206b0825241016b21dc Mon Sep 17 00:00:00 2001 From: "C.W. Betts" Date: Sun, 12 Jan 2025 16:16:40 -0700 Subject: [PATCH] Documentation pokes. --- Boxer/BXAboutController.h | 6 +-- Boxer/BXBezelController.h | 2 +- Boxer/BXBinCueImageImport.h | 4 +- Boxer/BXBlueprintBackgroundView.h | 2 +- Boxer/BXBlueprintPanel.h | 2 +- Boxer/BXBootlegCoverArt.h | 4 +- Boxer/BXCDImageImport.h | 2 +- Boxer/BXDockTileController.h | 4 +- Boxer/BXDrive+BXDriveArchiving.h | 2 +- Boxer/BXDrive.h | 42 ++++++++++--------- Boxer/BXDriveBundleImport.h | 2 +- Boxer/BXDriveImport.h | 10 +++-- Boxer/BXDrivesInUseAlert.h | 2 +- Boxer/BXEventConstants.h | 4 +- Boxer/BXFilterGallery.h | 4 +- Boxer/BXGamesFolderPanelController.h | 2 +- Boxer/BXHIDControllerProfile.h | 12 +++--- Boxer/BXHIDControllerProfilePrivate.h | 24 +++++------ Boxer/BXHIDInputBinding.h | 6 +-- Boxer/BXHelpMenuController.h | 2 +- Boxer/BXImportDropzone.h | 4 +- Boxer/BXImportDropzonePanelController.h | 2 +- Boxer/BXImportFinalizingPanelController.h | 8 ++-- Boxer/BXImportFinishedPanelController.h | 4 +- Boxer/BXImportInstallerPanelController.h | 4 +- Boxer/BXImportWindowController.h | 7 ++-- Boxer/BXJoystickController.h | 4 +- Boxer/BXMountPanelController.h | 6 +-- Boxer/BXPreferencesController.h | 8 ++-- Boxer/BXShelfArt.h | 8 ++-- Boxer/BXSimpleDriveImport.h | 2 +- Boxer/BXValueTransformers.h | 19 ++++----- Boxer/BXWelcomeButtonDraggingDelegate.h | 4 +- Boxer/BXWelcomeWindowController.h | 2 +- Boxer/BootlegCoverArt.swift | 22 ++++------ Boxer/DOS window/BXDOSWindow.h | 4 +- Boxer/DOS window/BXDOSWindowBackgroundView.h | 2 +- Boxer/DOS window/BXDOSWindowController.h | 9 ++-- Boxer/DOS window/BXDOSWindowControllerLion.h | 2 +- .../DOS window/BXDOSWindowControllerPrivate.h | 12 +++--- .../BXInputController+BXJoystickInput.h | 8 ++-- .../BXInputController+BXKeyboardInput.h | 2 +- Boxer/DOS window/BXInputController.h | 15 +++---- Boxer/DOS window/BXInputControllerPrivate.h | 4 +- Boxer/DOS window/BXInputView.h | 2 +- Boxer/DOS window/BXLaunchPanelController.h | 6 ++- Boxer/DOS window/BXProgramPanel.h | 2 +- Boxer/DOS window/BXProgramPanelController.h | 4 +- .../BXDocumentationBrowser.h | 20 +++++---- .../BXDocumentationPanelController.h | 8 ++-- Boxer/Input/BXOutputBinding.h | 2 +- Boxer/Inspector Panel/BXCoverArtWell.h | 4 +- Boxer/Inspector Panel/BXDriveItem.h | 8 ++-- Boxer/Inspector Panel/BXDriveList.h | 2 +- .../Inspector Panel/BXDrivePanelController.h | 4 +- .../BXGameboxPanelController.h | 4 +- Boxer/Inspector Panel/BXInspectorController.h | 4 +- Boxer/MT32LCDDisplay.swift | 2 +- Other Sources/ADBToolkit/ADBOperation.h | 15 +++---- 59 files changed, 198 insertions(+), 189 deletions(-) diff --git a/Boxer/BXAboutController.h b/Boxer/BXAboutController.h index fbf24890c..0c73ee8ab 100644 --- a/Boxer/BXAboutController.h +++ b/Boxer/BXAboutController.h @@ -8,16 +8,16 @@ #import -/// \c BXAboutController is a simple window controller which styles and displays the About Boxer panel. +/// `BXAboutController` is a simple window controller which styles and displays the About Boxer panel. @interface BXAboutController : NSWindowController @property (strong, nonatomic) IBOutlet NSTextField *version; /// Provides a singleton instance of the window controller which stays retained for the lifetime -/// of the application. BXAboutController should always be accessed from this singleton. +/// of the application. `BXAboutController` should always be accessed from this singleton. @property (class, readonly, strong) id controller; -//Display the credits and acknowledgements help page +/// Display the credits and acknowledgements help page. - (IBAction) showAcknowledgements: (id)sender; @end diff --git a/Boxer/BXBezelController.h b/Boxer/BXBezelController.h index 5b8350a6b..3fc23eeea 100644 --- a/Boxer/BXBezelController.h +++ b/Boxer/BXBezelController.h @@ -103,7 +103,7 @@ NS_ENUM(NSInteger) { #pragma mark Methods /// Whether to show or suppress drive notifications. -/// This will return NO if the Drives Inspector panel is open. +/// This will return `NO` if the Drives Inspector panel is open. - (BOOL) shouldShowDriveNotifications; - (void) showDriveAddedBezelForDrive: (BXDrive *)drive; diff --git a/Boxer/BXBinCueImageImport.h b/Boxer/BXBinCueImageImport.h index 708348af7..d720b950c 100644 --- a/Boxer/BXBinCueImageImport.h +++ b/Boxer/BXBinCueImageImport.h @@ -8,8 +8,8 @@ #import "BXCDImageImport.h" -/// \c BXBinCueImageImport rips CD-ROM discs to BIN/CUE images that are bundled into a .cdmedia bundle, -/// using the cdrdao utility. +/// `BXBinCueImageImport` rips CD-ROM discs to BIN/CUE images that are bundled into a .cdmedia bundle, +/// using the *cdrdao* utility. @interface BXBinCueImageImport : BXCDImageImport /// Enables/disables cdrdao's error-correction when reading audio tracks. diff --git a/Boxer/BXBlueprintBackgroundView.h b/Boxer/BXBlueprintBackgroundView.h index cfdffb562..386a01d1e 100644 --- a/Boxer/BXBlueprintBackgroundView.h +++ b/Boxer/BXBlueprintBackgroundView.h @@ -7,7 +7,7 @@ #import "BXDOSWindowBackgroundView.h" -/// BXBlueprintBackgroundView draws the custom blueprint background and watermark for the DOS window +/// `BXBlueprintBackgroundView` draws the custom blueprint background and watermark for the DOS window /// while importing a game. @interface BXBlueprintBackgroundView : BXDOSWindowBackgroundView @end diff --git a/Boxer/BXBlueprintPanel.h b/Boxer/BXBlueprintPanel.h index f287c210d..fef8ee10a 100644 --- a/Boxer/BXBlueprintPanel.h +++ b/Boxer/BXBlueprintPanel.h @@ -11,7 +11,7 @@ #import #import "BXHUDSpinningProgressIndicator.h" -/// \c BXBlueprintPanel and friends render a custom blueprint appearance for views in the import process. +/// `BXBlueprintPanel` and friends render a custom blueprint appearance for views in the import process. @interface BXBlueprintPanel : NSView @end diff --git a/Boxer/BXBootlegCoverArt.h b/Boxer/BXBootlegCoverArt.h index 12e98f1c9..749d1f5b1 100644 --- a/Boxer/BXBootlegCoverArt.h +++ b/Boxer/BXBootlegCoverArt.h @@ -10,12 +10,12 @@ NS_ASSUME_NONNULL_BEGIN -/// BXBootlegCoverArt is similar to BXCoverArt, but creates generic cover art based on a title string +/// `BXBootlegCoverArt` is similar to `BXCoverArt`, but creates generic cover art based on a title string /// rather than a box image. Implementing classes create artwork to resemble bootleg floppy disks and /// CD-ROM jewel-cases. @protocol BXBootlegCoverArt -/// Return a new BXBootlegCoverArt implementor using the specified title. +/// Return a new `BXBootlegCoverArt` implementor using the specified title. - (instancetype) initWithTitle: (NSString *)coverTitle; /// The game title to display on this cover art. diff --git a/Boxer/BXCDImageImport.h b/Boxer/BXCDImageImport.h index 46495352b..8d67f775f 100644 --- a/Boxer/BXCDImageImport.h +++ b/Boxer/BXCDImageImport.h @@ -19,7 +19,7 @@ typedef NS_ERROR_ENUM(BXCDImageImportErrorDomain, BXCDImageImportErrors) { }; -/// BXCDImageImport rips physical CDs to (CDR-format) ISO disc images using OS X's hdiutil. +/// `BXCDImageImport` rips physical CDs to (CDR-format) ISO disc images using macOS' hdiutil. @interface BXCDImageImport : ADBTaskOperation @property (atomic) unsigned long long numBytes; diff --git a/Boxer/BXDockTileController.h b/Boxer/BXDockTileController.h index 30a3c9e17..c5deb8fe0 100644 --- a/Boxer/BXDockTileController.h +++ b/Boxer/BXDockTileController.h @@ -10,13 +10,13 @@ @class BXSession; -/// \c BXDockTileController is a standalone class that listens for changes to the active DOS session +/// `BXDockTileController` is a standalone class that listens for changes to the active DOS session /// and changes the Boxer dock icon to match the current session's gamebox icon (if any). /// This class is instantiated in MainMenu.xib. @interface BXDockTileController : NSObject /// Called whenever the current session or its icon changes. -/// This calls \c coverArtForSession: with the current session and sets NSApplication's icon to the result. +/// This calls `coverArtForSession:` with the current session and sets NSApplication's icon to the result. - (void) syncIconWithActiveSession; @end diff --git a/Boxer/BXDrive+BXDriveArchiving.h b/Boxer/BXDrive+BXDriveArchiving.h index a8adc98d6..3dc348f64 100644 --- a/Boxer/BXDrive+BXDriveArchiving.h +++ b/Boxer/BXDrive+BXDriveArchiving.h @@ -8,7 +8,7 @@ #import "BXDrive.h" -/// \c BXDriveSerialization extends BXDrive with support for encoding and decoding from keyed archives. +/// \c BXDriveSerialization extends `BXDrive` with support for encoding and decoding from keyed archives. /// This is used for remembering mounted drives across sessions. @interface BXDrive (BXDriveArchiving) diff --git a/Boxer/BXDrive.h b/Boxer/BXDrive.h index dfef1981b..e046e9783 100644 --- a/Boxer/BXDrive.h +++ b/Boxer/BXDrive.h @@ -22,7 +22,7 @@ typedef NS_ENUM(NSInteger, BXDriveType) { BXDriveVirtual = 3 }; -/// Setting freeSpace to @c BXDefaultFreeSpace indicates that the drive should use whatever free space DOSBox thinks is best. +/// Setting `freeSpace` to `BXDefaultFreeSpace` indicates that the drive should use whatever free space DOSBox thinks is best. #define BXDefaultFreeSpace -1l @@ -31,27 +31,27 @@ typedef NS_ENUM(NSInteger, BXDriveType) { @protocol ADBFilesystemPathAccess, ADBFilesystemLogicalURLAccess; -/// \c BXDrive represents a single DOS drive and encapsulates all the data needed to mount the drive -/// and locate it on the OS X filesystem. BXDrives are mounted via ADBFilesystem's @c mountDrive: method. +/// `BXDrive` represents a single DOS drive and encapsulates all the data needed to mount the drive +/// and locate it on the OS X filesystem. BXDrives are mounted via ADBFilesystem's `mountDrive:` method. @interface BXDrive : NSObject #pragma mark - Properties -/// The location on the OS X filesystem of this drive's contents. +/// The location on the macOS filesystem of this drive's contents. /// This is the canonical location of the drive and is used when resolving absolute /// URLs to DOS filesystem paths. It may or may not be the same as the location that -/// actually gets mounted in DOSBox: see @c mountPointURL below. +/// actually gets mounted in DOSBox: see `-mountPointURL` below. /// /// Several properties are derived automatically from the source URL: Changing the /// source URL will recalculate mountPointURL, letter, title, volumeLabel and type /// unless these have been explicitly overridden. @property (copy, nonatomic, nullable) NSURL *sourceURL; -/// The OS X filesystem location that will be mounted in DOSBox. +/// The macOS filesystem location that will be mounted in DOSBox. /// Usually this is the same as the source URL, but differs for e.g. CD-ROM bundles. @property (copy, nonatomic, nullable) NSURL *mountPointURL; -/// An optional location on the OS X filesystem to which we will perform +/// An optional location on the macOS filesystem to which we will perform /// shadow write operations for this drive. That is, any files that are /// opened for modification on this drive will be silently written to this /// location instead of creating/modifying files in the original location. @@ -59,7 +59,7 @@ typedef NS_ENUM(NSInteger, BXDriveType) { /// The DOS drive letter under which this drive will be mounted. -/// If nil, @c BXEmulator will choose an appropriate drive letter at mount time +/// If `nil`, `BXEmulator` will choose an appropriate drive letter at mount time /// (and update this property with the chosen letter). @property (copy, nonatomic, nullable) NSString *letter; @@ -73,18 +73,18 @@ typedef NS_ENUM(NSInteger, BXDriveType) { @property (copy, nonatomic, nullable) NSString *volumeLabel; /// The volume label that the drive ended up with after mounting in DOS. -/// This is populated by BXEmulator when the drive is first mounted and will be a munged +/// This is populated by `BXEmulator` when the drive is first mounted and will be a munged /// version of the above: cropped to 11 characters and uppercased for most drive types. @property (copy, nonatomic, nullable) NSString *DOSVolumeLabel; /// The amount of free disk space to report for the drive, in bytes. Defaults to -/// BXDefaultFreeSpace: which is ~250MB for hard disks, 1.44MB for floppies and 0B for CDROMs. +/// `BXDefaultFreeSpace`: which is ~250MB for hard disks, 1.44MB for floppies and 0B for CDROMs. /// Note that this is not an enforced limit: it only affects how much free space is reported /// to DOS programs. @property (nonatomic) NSInteger freeSpace; /// Whether to use SDL CD-ROM audio: only relevant for folders mounted as CD-ROM drives. -/// If YES, DOS emulation will read CD audio for this drive from the first audio CD volume mounted in OS X. +/// If `YES`, DOS emulation will read CD audio for this drive from the first audio CD volume mounted in OS X. @property (nonatomic) BOOL usesCDAudio; /// Whether to prevent DOS from writing to the OS X filesystem representing this drive. Defaults to NO. @@ -101,7 +101,7 @@ typedef NS_ENUM(NSInteger, BXDriveType) { @property (nonatomic, getter=isHidden) BOOL hidden; /// Whether this drive is currently mounted in an emulation session. -/// This is merely a flag to make displaying the state of a drive easier; setting it to @c YES +/// This is merely a flag to make displaying the state of a drive easier; setting it to `YES` /// will not actually mount the drive, just indicate that it is mounted somewhere. @property (nonatomic, getter=isMounted) BOOL mounted; @@ -132,8 +132,9 @@ typedef NS_ENUM(NSInteger, BXDriveType) { /// Returns a localised descriptive name for the specified drive type. e.g. @"hard disk", @"CD-ROM" etc. + (NSString *) localizedDescriptionForType: (BXDriveType)driveType; -/// Determines the most appropriate drive type for the specified file or folder. This is based on: +/// Determines the most appropriate drive type for the specified file or folder. /// +/// This is based on: /// 1. the file's type identifier: e.g. disk images will be treated as CD-ROM or floppy drives; /// 2. the filesystem of the URL's volume: e.g. folders located on a CD-ROM volume will be detected as CD-ROMs. + (BXDriveType) preferredTypeForContentsOfURL: (NSURL *)URL; @@ -142,7 +143,7 @@ typedef NS_ENUM(NSInteger, BXDriveType) { /// /// For regular folders and CD-ROM volumes, this will be their filename; /// For .floppy, .cdrom, .cdmedia and .harddisk folders, this will be their filename -/// minus extension and parsed drive letter (see @c preferredDriveLetterForContentsOfURL: below.) +/// minus extension and parsed drive letter (see `-preferredDriveLetterForContentsOfURL:` below.) + (NSString *) preferredVolumeLabelForContentsOfURL: (NSURL *)URL; /// Determines a suitable display title for the specified location. @@ -150,7 +151,7 @@ typedef NS_ENUM(NSInteger, BXDriveType) { + (NSString *) preferredTitleForContentsOfURL: (NSURL *)URL; /// Determines a recommended drive letter from the specified location, -/// or @c nil if no specific drive letter is appropriate. +/// or `nil` if no specific drive letter is appropriate. /// /// If the location is a disk image or a Boxer mountable folder, and the filename starts with a single /// letter followed by a space, this will be parsed out and used as the drive letter. @@ -164,9 +165,10 @@ typedef NS_ENUM(NSInteger, BXDriveType) { #pragma mark - Constructors /// Returns a newly-minted drive instance representing the contents of the specified URL. -/// If driveLetter is specified, this will be used; if it is left nil, an appropriate drive +/// +/// If `driveLetter` is specified, this will be used; if it is left `nil`, an appropriate drive /// letter will be determined when the drive is first mounted. -/// If driveType is specified, a drive of that type will be created; if it is BXDriveTypeAuto, +/// If `driveType` is specified, a drive of that type will be created; if it is `BXDriveTypeAuto`, /// the most appropriate type will be determined from the contents of the URL. - (instancetype) initWithContentsOfURL: (nullable NSURL *)sourceURL letter: (nullable NSString *)driveLetter @@ -191,8 +193,8 @@ typedef NS_ENUM(NSInteger, BXDriveType) { - (BOOL) exposesLogicalURL: (NSURL *)URL; /// Returns the location of the specified logical URL relative to the filesystem of the drive: -/// or @c nil if the specified location is not contained on this drive. -/// Used by @c BXDOSFileSystem for matching OS X filesystem paths with DOS filesystem paths. +/// or `nil` if the specified location is not contained on this drive. +/// Used by `BXDOSFileSystem` for matching macOS filesystem paths with DOS filesystem paths. - (nullable NSString *) relativeLocationOfLogicalURL: (NSURL *)URL; /// Returns a logical URL representing the specified DOS path, as constructed by the drive's filesystem. @@ -202,7 +204,7 @@ typedef NS_ENUM(NSInteger, BXDriveType) { /// Indicates that the specified URL represents the same resource as the contents of this drive. /// This is used by the drive's filesystem to correctly resolve URLs to resources in different apparent locations. /// Mainly this is of use for drives representing disk images: so that if the image is mounted -/// as a folder in OS X, the drive will treat locations within the mounted folder as being contained +/// as a folder in macOS, the drive will treat locations within the mounted folder as being contained /// within the drive. - (void) addEquivalentURL: (NSURL *)URL; diff --git a/Boxer/BXDriveBundleImport.h b/Boxer/BXDriveBundleImport.h index 6cac60a49..15c411564 100644 --- a/Boxer/BXDriveBundleImport.h +++ b/Boxer/BXDriveBundleImport.h @@ -17,7 +17,7 @@ NS_ERROR_ENUM(BXDriveBundleErrorDomain) { }; -/// BXDriveBundleImport wraps BIN/CUE images and any associated audio tracks into a .cdmedia bundle, +/// `BXDriveBundleImport` wraps BIN/CUE images and any associated audio tracks into a .cdmedia bundle, /// rewriting cue paths as necessary. @interface BXDriveBundleImport : ADBFileTransferSet @end diff --git a/Boxer/BXDriveImport.h b/Boxer/BXDriveImport.h index 3bf43decc..0d8a58399 100644 --- a/Boxer/BXDriveImport.h +++ b/Boxer/BXDriveImport.h @@ -18,8 +18,8 @@ extern NSString * const BXUniqueDriveNameFormat; @class BXDrive; -/// The \c BXDriveImport protocol defines the public interface for drive import operations, -/// which are expected to descend from NSOperation. BXDriveImport is also a class that defines a number +/// The `BXDriveImport` protocol defines the public interface for drive import operations, +/// which are expected to descend from `NSOperation`. `BXDriveImport` is also a class that defines a number /// of helper methods and factory methods for use by concrete import operations. @protocol BXDriveImport @@ -50,7 +50,7 @@ extern NSString * const BXUniqueDriveNameFormat; @property (class, readonly) BOOL driveUnavailableDuringImport; -/// Return a suitably initialized BXOperation subclass for transferring the drive. +/// Return a suitably initialized `BXOperation` subclass for transferring the drive. - (instancetype) initForDrive: (BXDrive *)drive destinationFolderURL: (NSURL *)destinationFolderURL copyFiles: (BOOL)copyFiles; @@ -71,9 +71,11 @@ extern NSString * const BXUniqueDriveNameFormat; + (nullable Class) importClassForDrive: (BXDrive *)drive; /// Returns a safe replacement import operation for the specified failed import, -/// or nil if no fallback was available. +/// or `nil` if no fallback was available. +/// /// The replacement will have the same source drive and destination folder as /// the original import. +/// /// Used when e.g. a disc-ripping import fails because of a driver-related issue: /// this will fall back on a safer method of importing. + (nullable id ) fallbackForFailedImport: (id )failedImport; diff --git a/Boxer/BXDrivesInUseAlert.h b/Boxer/BXDrivesInUseAlert.h index fe7d8707a..cc43376a5 100644 --- a/Boxer/BXDrivesInUseAlert.h +++ b/Boxer/BXDrivesInUseAlert.h @@ -11,7 +11,7 @@ @class BXSession; @class BXDrive; -/// \c BXDrivesInUseAlert is shown when a user tries to unmount one or more drives that are currently +/// `BXDrivesInUseAlert` is shown when a user tries to unmount one or more drives that are currently /// being accessed by the DOS process. It displays a warning and confirmation. @interface BXDrivesInUseAlert : NSAlert diff --git a/Boxer/BXEventConstants.h b/Boxer/BXEventConstants.h index e65276578..ece035fa7 100644 --- a/Boxer/BXEventConstants.h +++ b/Boxer/BXEventConstants.h @@ -32,7 +32,7 @@ /// Used as the arbitrary length for arrays of key mappings. #define BXMaxSystemKeyCode 256 -/// These correspond to NSEvent's mouse button numbers +/// These correspond to `NSEvent`'s mouse button numbers typedef NS_ENUM(NSInteger, BXMouseButton) { BXMouseButtonLeft = 0, BXMouseButtonRight = 1, @@ -41,7 +41,7 @@ typedef NS_ENUM(NSInteger, BXMouseButton) { }; -/// These correspond to NSEvent's pressedMouseButton masks +/// These correspond to `NSEvent`'s pressedMouseButton masks typedef NS_OPTIONS(NSUInteger, BXMouseButtonMask) { BXNoMouseButtonsMask = 0, BXMouseButtonLeftMask = 1U << BXMouseButtonLeft, diff --git a/Boxer/BXFilterGallery.h b/Boxer/BXFilterGallery.h index 16b126532..e64d9b7dd 100644 --- a/Boxer/BXFilterGallery.h +++ b/Boxer/BXFilterGallery.h @@ -8,8 +8,8 @@ #import -/// \c BXFilterGallery draws Boxer's rendering filter gallery in the preferences pane. It consists of -/// the \c BXFilterGallery view that renders a graphical background, containing BXFilterPortrait +/// `BXFilterGallery` draws Boxer's rendering filter gallery in the preferences pane. It consists of +/// the `BXFilterGallery` view that renders a graphical background, containing BXFilterPortrait /// buttons for each option. @interface BXFilterGallery : NSView @end diff --git a/Boxer/BXGamesFolderPanelController.h b/Boxer/BXGamesFolderPanelController.h index d27c933ca..50c46d1a2 100644 --- a/Boxer/BXGamesFolderPanelController.h +++ b/Boxer/BXGamesFolderPanelController.h @@ -8,7 +8,7 @@ #import -/// BXGamesFolderPanelController displays the choose-a-game-folder open panel, and manages its +/// `BXGamesFolderPanelController` displays the choose-a-game-folder open panel, and manages its /// accessory view. It is also responsible for adding sample games to the chosen folder, if requested. @interface BXGamesFolderPanelController : NSViewController diff --git a/Boxer/BXHIDControllerProfile.h b/Boxer/BXHIDControllerProfile.h index 55a402499..1507e2512 100644 --- a/Boxer/BXHIDControllerProfile.h +++ b/Boxer/BXHIDControllerProfile.h @@ -15,7 +15,7 @@ @protocol BXEmulatedJoystick; @protocol BXHIDInputBinding; -/// Constants used by BXHIDControllerProfile.controllerStyle. +/// Constants used by `BXHIDControllerProfile.controllerStyle`. typedef NS_ENUM(NSInteger, BXControllerStyle) { BXControllerStyleUnknown, BXControllerStyleJoystick, @@ -25,13 +25,13 @@ typedef NS_ENUM(NSInteger, BXControllerStyle) { }; -/// @c BXControllerProfile is paired with a @c DDHidDevice and maps actual HID events from that +/// `BXControllerProfile` is paired with a `DDHidDevice` and maps actual HID events from that /// device into inputs on emulated input devices. /// The class can programmatically design a suitable control mapping for a specified HID device /// based on the device's elements; it is also intended to be subclassed for devices that require /// more specific translation. -/// @c BXControllerProfile is controller- and joystick-specific and each emulation session maintains +/// `BXControllerProfile` is controller- and joystick-specific and each emulation session maintains /// its own set of active controller profiles. @interface BXHIDControllerProfile : NSObject @@ -42,19 +42,19 @@ typedef NS_ENUM(NSInteger, BXControllerStyle) { @property (strong, nonatomic) id emulatedJoystick; @property (strong, nonatomic) BXEmulatedKeyboard *emulatedKeyboard; -/// A dictionary of @c DDHidUsage -> @c BXHIDInputBinding mappings. +/// A dictionary of `DDHidUsage` -> `BXHIDInputBinding` mappings. @property (readonly, strong, nonatomic) NSMutableDictionary *bindings; /// The style of this controller. Used for tweaking certain mapping behaviours. @property (readonly, nonatomic) BXControllerStyle controllerStyle; -/// Returns a @c BXControllerProfile that maps the specified HID controller +/// Returns a `BXControllerProfile` that maps the specified HID controller /// to the specified emulated joystick. + (instancetype) profileForHIDDevice: (DDHidJoystick *)device emulatedJoystick: (id )joystick keyboard: (BXEmulatedKeyboard *)keyboard; -/// Returns a @c BXControllerProfile that maps the specified HID controller +/// Returns a `BXControllerProfile` that maps the specified HID controller /// to the specified emulated joystick. - (instancetype) initWithHIDDevice: (DDHidJoystick *)device emulatedJoystick: (id )joystick diff --git a/Boxer/BXHIDControllerProfilePrivate.h b/Boxer/BXHIDControllerProfilePrivate.h index bed53c4b0..258fcdb41 100644 --- a/Boxer/BXHIDControllerProfilePrivate.h +++ b/Boxer/BXHIDControllerProfilePrivate.h @@ -73,10 +73,10 @@ extern NSString * const BXControllerProfileDPadDown; - (void) bindButtonElements: (NSArray *)elements; - (void) bindPOVElements: (NSArray *)elements; -/// Called by \c bindAxisElements: to separate wheel-binding logic from regular axis binding. +/// Called by `-bindAxisElements:` to separate wheel-binding logic from regular axis binding. - (void) bindAxisElementsForWheel: (NSArray *)elements; -/// Returns a \c BXHIDInputBinding to bind the specified element on the profile's HID controller +/// Returns a `BXHIDInputBinding` to bind the specified element on the profile's HID controller /// to the profile's emulated joystick. Must return nil if the element should not be bound. /// Used by generateBindings and intended to be overridden by subclasses for individual bindings. - (id ) generatedBindingForAxisElement: (DDHidElement *)element; @@ -142,34 +142,34 @@ extern NSString * const BXControllerProfileDPadDown; #pragma mark Profile registration and matching /// Registers the specified profile subclass as a custom profile. -/// Should be called in each subclass's +load method. +/// Should be called in each subclass's `+load` method. + (void) registerProfile: (Class)profile; /// Returns whether the implementing class is suitable for the specified controller. -/// Used by BXHIDControllerProfile profileClassForrDevice: to find custom +/// Used by `+[BXHIDControllerProfile profileClassForrDevice:]` to find custom /// profile classes for known devices. /// Uses matchIDs by default, but can be overridden by subclasses to perform custom matching. + (BOOL) matchesDevice: (DDHidJoystick *)device; -/// Returns the BXHIDControllerProfile subclass most suited for the specified device, -/// falling back on BXHIDControllerProfile itself if none more suitable is found. +/// Returns the `BXHIDControllerProfile` subclass most suited for the specified device, +/// falling back on `BXHIDControllerProfile` itself if none more suitable is found. /// Should not be overridden. + (Class) profileClassForDevice: (DDHidJoystick *)device; -/// Returns an array of NSDictionaries containing vendorID and usageID pairs, -/// which this profile should match. Used by matchesDevice:. -/// Returns an empty array by default, and is intended to be overridden by subclasses. +/// Returns an array of `NSDictionaries` containing *vendorID* and *usageID* pairs, +/// which this profile should match. Used by `+matchesDevice:`. +/// Returns an empty array by default, and is intended to be overridden by subclasses. + (NSArray*> *) matchedIDs; -/// Helper method for generating match definitions. For use by subclasses overriding matchedIDs. +/// Helper method for generating match definitions. For use by subclasses overriding `+matchedIDs`. + (NSDictionary *) matchForVendorID: (uint16_t)vendorID productID: (uint16_t)productID; #pragma mark - #pragma mark Event handling -/// Returns \c YES if the specified event should be dispatched to an available binding, -/// or \c NO if the event should be ignored. The default implementation always returns YES. +/// Returns `YES` if the specified event should be dispatched to an available binding, +/// or `NO` if the event should be ignored. The default implementation always returns `YES`. - (BOOL) shouldDispatchHIDEvent: (ADBHIDEvent *)event; @end diff --git a/Boxer/BXHIDInputBinding.h b/Boxer/BXHIDInputBinding.h index 283092b98..f2581449f 100644 --- a/Boxer/BXHIDInputBinding.h +++ b/Boxer/BXHIDInputBinding.h @@ -48,7 +48,7 @@ NS_ASSUME_NONNULL_BEGIN /// and 0.0 when the axis is centered or positive. @property (strong, nonatomic, nullable) id negativeBinding; -/// If YES, axis input will be flipped (meaning the negative binding will be triggered +/// If `YES`, axis input will be flipped (meaning the negative binding will be triggered /// when the axis is positive, and vice-versa). @property (assign, nonatomic, getter=isInverted) BOOL inverted; @@ -56,7 +56,7 @@ NS_ASSUME_NONNULL_BEGIN @property (assign, nonatomic) float deadzone; /// Whether this is a trigger-style axis with only one direction of travel. -/// If YES, the full -1.0->1.0 input range will be mapped to 0.0->1.0 before inverting. +/// If `YES`, the full -1.0->1.0 input range will be mapped to 0.0->1.0 before inverting. @property (assign, nonatomic, getter=isUnidirectional) BOOL unidirectional; + (instancetype) bindingWithPositiveBinding: (nullable id )positiveBinding @@ -67,7 +67,7 @@ NS_ASSUME_NONNULL_BEGIN @interface BXHIDPOVSwitchBinding : NSObject -/// Creates a new binding from interleaved pairs of bindings and directions, followed by a \c nil sentinel. +/// Creates a new binding from interleaved pairs of bindings and directions, followed by a `nil` sentinel. + (instancetype) bindingWithOutputBindingsAndDirections: (id )binding, ... NS_REQUIRES_NIL_TERMINATION; /// Set/get the binding for a particular cardinal POV direction. diff --git a/Boxer/BXHelpMenuController.h b/Boxer/BXHelpMenuController.h index 592879a62..927ae9ff3 100644 --- a/Boxer/BXHelpMenuController.h +++ b/Boxer/BXHelpMenuController.h @@ -10,7 +10,7 @@ @class BXSession; -/// \c BXHelpMenuController manages the Boxer Help menu and its actions. When a DOS session is active, +/// `BXHelpMenuController` manages the Boxer Help menu and its actions. When a DOS session is active, /// it populates the help menu with documentation files found within the session's gamebox (if any) /// and links to look up the game on Mobygames or Replacementdocs. /// This controller is instantiated in MainMenu.xib. diff --git a/Boxer/BXImportDropzone.h b/Boxer/BXImportDropzone.h index a4b0c744c..edd6ad0ad 100644 --- a/Boxer/BXImportDropzone.h +++ b/Boxer/BXImportDropzone.h @@ -10,10 +10,10 @@ NS_ASSUME_NONNULL_BEGIN -/// \c BXImportDropzone is used in the game import window to draw a dashed dropzone region, +/// `BXImportDropzone` is used in the game import window to draw a dashed dropzone region, /// which animates while an importable file is dragged over the panel, and which displays /// the file's icon after dropping. Clicking the region will reveal a file picker. -/// (\c BXImportDropzone does not actually handle drag-drop events itself: the panel itself does that.) +/// (`BXImportDropzone` does not actually handle drag-drop events itself: the panel itself does that.) @interface BXImportDropzone : NSButton //Whether we're the target of a drag-drop operation. When YES, the dropzone's border will animate. diff --git a/Boxer/BXImportDropzonePanelController.h b/Boxer/BXImportDropzonePanelController.h index 45a254dbb..6d25a2692 100644 --- a/Boxer/BXImportDropzonePanelController.h +++ b/Boxer/BXImportDropzonePanelController.h @@ -12,7 +12,7 @@ @class BXImportWindowController; @class BXBlueprintProgressIndicator; -/// \c BXImportDropzonePanelController controls the behaviour of the dropzone panel +/// `BXImportDropzonePanelController` controls the behaviour of the dropzone panel /// in the game import process. @interface BXImportDropzonePanelController : NSViewController diff --git a/Boxer/BXImportFinalizingPanelController.h b/Boxer/BXImportFinalizingPanelController.h index 78624295a..c21d2d971 100644 --- a/Boxer/BXImportFinalizingPanelController.h +++ b/Boxer/BXImportFinalizingPanelController.h @@ -11,14 +11,14 @@ @class BXImportWindowController; -/// \c BXImportFinalizingPanelController manages the finalizing-gamebox view of the game import window. +/// `BXImportFinalizingPanelController` manages the finalizing-gamebox view of the game import window. @interface BXImportFinalizingPanelController : NSViewController #pragma mark - #pragma mark Properties /// A back-reference to our owning window controller. -@property (unsafe_unretained, nonatomic) IBOutlet BXImportWindowController *controller; +@property (weak, nonatomic) IBOutlet BXImportWindowController *controller; /// A textual description of what import stage we are currently performing. /// Used for populating the description field beneath the progress bar. @@ -29,14 +29,14 @@ @property (readonly, nonatomic) BOOL cancelButtonEnabled; /// Whether to show the tip about importing additional CDs. -/// Will be \c YES if the source is a CD-ROM or CD image, NO otherwise. +/// Will be `YES` if the source is a CD-ROM or CD image, NO otherwise. @property (readonly, nonatomic) BOOL showAdditionalCDTips; #pragma mark - #pragma mark Helper class methods -/// Helper methods used by progressDescription and cancelButtonLabel. +/// Helper methods used by `progressDescription` and `cancelButtonLabel`. + (NSString *) cancelButtonLabelForImportType: (BXSourceFileImportType)importType; + (NSString *) stageDescriptionForImportType: (BXSourceFileImportType)importType; diff --git a/Boxer/BXImportFinishedPanelController.h b/Boxer/BXImportFinishedPanelController.h index 852f3eecd..72cca1bda 100644 --- a/Boxer/BXImportFinishedPanelController.h +++ b/Boxer/BXImportFinishedPanelController.h @@ -11,12 +11,12 @@ @class BXImportIconDropzone; @class BXImportWindowController; -/// \c BXImportFinishedPanelController controls the appearance and behaviour of the final +/// `BXImportFinishedPanelController` controls the appearance and behaviour of the final /// your-gamebox-is-finished panel of the import process. @interface BXImportFinishedPanelController : NSViewController /// A back-reference to our owning window controller. -@property (unsafe_unretained, nonatomic) IBOutlet BXImportWindowController *controller; +@property (weak, nonatomic) IBOutlet BXImportWindowController *controller; /// The image well that displays the gamebox icon. @property (strong, nonatomic) IBOutlet BXImportIconDropzone *iconView; diff --git a/Boxer/BXImportInstallerPanelController.h b/Boxer/BXImportInstallerPanelController.h index 7078c3fb3..5a79611dc 100644 --- a/Boxer/BXImportInstallerPanelController.h +++ b/Boxer/BXImportInstallerPanelController.h @@ -15,7 +15,7 @@ NS_ASSUME_NONNULL_BEGIN @class BXImportWindowController; -/// \c BXImportInstallerPanelController controls the behaviour of the choose-thine-installer panel +/// `BXImportInstallerPanelController` controls the behaviour of the choose-thine-installer panel /// in the game import process. @interface BXImportInstallerPanelController : NSViewController < NSOpenSavePanelDelegate > @@ -26,7 +26,7 @@ NS_ASSUME_NONNULL_BEGIN @property (strong, nonatomic) IBOutlet NSPopUpButton *installerSelector; /// Whether we can show a menu option to let the user pick an installer from an open panel. -/// Will be \c NO if the source URL of the import is a disk image, rather than a folder. +/// Will be `NO` if the source URL of the import is a disk image, rather than a folder. @property (readonly, nonatomic) BOOL canBrowseInstallers; #pragma mark - diff --git a/Boxer/BXImportWindowController.h b/Boxer/BXImportWindowController.h index 8f2667c19..e1fec55fc 100644 --- a/Boxer/BXImportWindowController.h +++ b/Boxer/BXImportWindowController.h @@ -10,9 +10,10 @@ @class BXImportSession; -/// \c BXImportWindowController manages the behaviour of the drive import window and coordinates +/// `BXImportWindowController` manages the behaviour of the drive import window and coordinates /// animation and transitions between the window's various views. -/// It takes its marching orders from the BXImportSession document class. +/// +/// It takes its marching orders from the `BXImportSession` document class. @interface BXImportWindowController : ADBMultiPanelWindowController #pragma mark - @@ -35,7 +36,7 @@ @property (strong, nonatomic) IBOutlet NSView *finishedPanel; -/// Recast NSWindowController's standard accessors so that we get our own classes +/// Recast `NSWindowController`'s standard accessors so that we get our own classes /// (and don't have to keep recasting them ourselves.) - (BXImportSession *) document; diff --git a/Boxer/BXJoystickController.h b/Boxer/BXJoystickController.h index 81220ca6b..23c0972e1 100644 --- a/Boxer/BXJoystickController.h +++ b/Boxer/BXJoystickController.h @@ -10,14 +10,14 @@ #import #import "ADBHIDMonitor.h" -/// \c BXJoystickController receives joystick input from connected controllers via the DDHidLib toolkit. +/// `BXJoystickController` receives joystick input from connected controllers via the DDHidLib toolkit. /// These messages are then translated into a more Boxer-friendly format and sent onwards to the /// active DOS session's input controller. @interface BXJoystickController: NSObject @property (readonly, strong, nonatomic) ADBHIDMonitor *HIDMonitor; -/// An array of\c DDHIDJoystick instances for each joystick currently connected. +/// An array of `DDHIDJoystick` instances for each joystick currently connected. /// Corresponds to hidMonitor matchedDevices. @property (copy, readonly, nonatomic) NSArray *joystickDevices; diff --git a/Boxer/BXMountPanelController.h b/Boxer/BXMountPanelController.h index b44eeebb2..0c668abaf 100644 --- a/Boxer/BXMountPanelController.h +++ b/Boxer/BXMountPanelController.h @@ -11,8 +11,8 @@ @class BXSession; -/// \c BXMountPanelController displays the mount-a-new-drive open panel and manages its accessory view. -/// It is responsible for synchronising the drive-settings fields with the current file selection, +/// `BXMountPanelController` displays the mount-a-new-drive open panel and manages its accessory view. +/// It is responsible for synchronising the drive-settings fields with the current file selection, /// and for calling the relevant mount commands once a file is chosen. @interface BXMountPanelController : NSViewController @@ -40,7 +40,7 @@ - (void) syncMountOptionsForPanel: (NSOpenPanel *)openPanel; /// Mounts the specified selected file or folder, chosen from the open panel. -/// Returns \c YES if successfully, or NO and populates outError if the drive could not be mounted. +/// Returns `YES` if successfully, or `NO` and populates `outError` if the drive could not be mounted. - (BOOL) mountChosenURL: (NSURL *)URL error: (NSError **)outError; @end diff --git a/Boxer/BXPreferencesController.h b/Boxer/BXPreferencesController.h index 597da7a21..17310c9e7 100644 --- a/Boxer/BXPreferencesController.h +++ b/Boxer/BXPreferencesController.h @@ -11,7 +11,7 @@ @class BXFilterGallery; @class BXMT32ROMDropzone; -/// BXPreferencesController manages Boxer's application-wide preferences panel. +/// `BXPreferencesController` manages Boxer's application-wide preferences panel. /// It is a singleton, and once opened for the first time it stays alive throughout the lifetime of the application. @interface BXPreferencesController : ADBTabbedWindowController @@ -55,14 +55,14 @@ /// Provides a singleton instance of the window controller which stays retained for the lifetime -/// of the application. BXPreferencesController should always be accessed from this singleton. +/// of the application. `BXPreferencesController` should always be accessed from this singleton. + (BXPreferencesController *) controller; #pragma mark - Filter gallery controls /// Change the default render filter to match the sender's tag. -/// @note that there is also a @c -toggleRenderingStyle: defined on @c BXDOSWindowController +/// - note: that there is also a `-toggleRenderingStyle:` defined on `BXDOSWindowController` /// and used by main menu items, which does the same thing. This uses an intentionally different /// name so as not to collide, as the two sets of controls need to be validated differently. - (IBAction) toggleDefaultRenderingStyle: (id)sender; @@ -84,7 +84,7 @@ /// Reveal Boxer's MT-32 ROMs folder (located inside Application Support) in a Finder window /// and selects the currently-installed ROMs within that folder. /// This creates the folder if it doesn't already exist. -/// @see BXBaseAppController+BXSupportFiles @c-MT32ROMURLCreatingIfMissing:error: +/// @see BXBaseAppController+BXSupportFiles @c -MT32ROMURLCreatingIfMissing:error: - (IBAction) showMT32ROMsInFinder: (id)sender; /// Show a standard OS X open panel for choosing MT-32 ROMs to install. diff --git a/Boxer/BXShelfArt.h b/Boxer/BXShelfArt.h index c8e207642..c718451a9 100644 --- a/Boxer/BXShelfArt.h +++ b/Boxer/BXShelfArt.h @@ -9,7 +9,7 @@ #import -/// \c BXShelfArt generates tiled shelf artwork for Finder folders. It can return an NSImage resource +/// `BXShelfArt` generates tiled shelf artwork for Finder folders. It can return an `NSImage` resource /// suitable for saving as a file, or draw the art directly into the current graphics context. @interface BXShelfArt : NSObject @@ -19,7 +19,7 @@ #pragma mark - #pragma mark Initialization and teardown -/// Default initializer: returns a BXShelfArt object initialized with the specified source image. +/// Default initializer: returns a `BXShelfArt` object initialized with the specified source image. - (instancetype) initWithSourceImage: (NSImage *)image; @@ -29,10 +29,10 @@ /// Draws the source image tiled into the specified frame in the current graphics context. - (void) drawInRect: (NSRect)frame; -/// Returns a new NSImage containing the source image tiled to fill the logical unit size. +/// Returns a new `NSImage` containing the source image tiled to fill the logical unit size. - (NSImage *) tiledImageWithSize: (NSSize)size; -/// Returns a new NSImage containing the source image tiled to fill the specific device pixel size. +/// Returns a new `NSImage` containing the source image tiled to fill the specific device pixel size. - (NSImage *) tiledImageWithPixelSize: (NSSize)pixelSize; @end diff --git a/Boxer/BXSimpleDriveImport.h b/Boxer/BXSimpleDriveImport.h index 5a8f3c711..151369869 100644 --- a/Boxer/BXSimpleDriveImport.h +++ b/Boxer/BXSimpleDriveImport.h @@ -11,6 +11,6 @@ @class BXDrive; -/// \c BXSimpleDriveImport handles the importing of a drive to a specified destination. +/// `BXSimpleDriveImport` handles the importing of a drive to a specified destination. @interface BXSimpleDriveImport : ADBSingleFileTransfer @end diff --git a/Boxer/BXValueTransformers.h b/Boxer/BXValueTransformers.h index 3d827ef85..03591a0e5 100644 --- a/Boxer/BXValueTransformers.h +++ b/Boxer/BXValueTransformers.h @@ -32,8 +32,8 @@ @end -/// Returns the NSNumber equivalents of \c YES or \c NO based on whether an array's size is within the min and max range of the transformer. -/// Registered as \c BXIsEmpty and \c BXIsNotEmpty by BXAppController, which are used for detecting whether an array is empty or not. +/// Returns the NSNumber equivalents of `YES` or `NO` based on whether an array's size is within the min and max range of the transformer. +/// Registered as `BXIsEmpty` and `BXIsNotEmpty` by `BXAppController`, which are used for detecting whether an array is empty or not. @interface BXArraySizeTransformer : NSValueTransformer @property (nonatomic) NSUInteger minSize; @property (nonatomic) NSUInteger maxSize; @@ -43,15 +43,14 @@ /// Simply inverts a number and returns it. -/// Registered as \c BXFrameRateSliderTransformer by BXSession+BXEmulatorControls, which is used for flipping the values of the framerate slider. +/// Registered as `BXFrameRateSliderTransformer` by BXSession+BXEmulatorControls, which is used for flipping the values of the framerate slider. @interface BXInvertNumberTransformer: NSValueTransformer @end - +#define MAX_BANDS 32 /// Maps sets of numeric ranges (0-1000, 1001-2000 etc.) onto a 0.0->1.0 scale, with equal weight for each range. -/// Registered as \c BXSpeedSliderTransformer by BXSession+BXEmulatorControls, to maps our different CPU speed bands onto a single speed slider. +/// Registered as `BXSpeedSliderTransformer` by BXSession+BXEmulatorControls, to maps our different CPU speed bands onto a single speed slider. /// NOTE: sliders using this transformer must have a range from 0.0 to 1.0. -#define MAX_BANDS 32 @interface BXBandedValueTransformer: NSValueTransformer - (id) initWithThresholds: (double *)thresholds count: (NSUInteger)count; @@ -94,18 +93,18 @@ /// Converts a POSIX path into a breadcrumb-style representation with file icons /// for each part of the file path. Unlike BXDisplayPathTransformer, this returns -/// an \c NSAttributedString rather than an NSString. +/// an `NSAttributedString` rather than an NSString. @interface BXIconifiedDisplayPathTransformer: BXDisplayPathTransformer /// The file icon to use for files/folders that don't yet exist. /// If left as nil, will use NSWorkspace's default icon for missing files. @property (copy, nonatomic) NSImage *missingFileIcon; -/// The NSAttributedString attributes to apply to the final text. +/// The `NSAttributedString` attributes to apply to the final text. /// Defaults to the standard system font. @property (strong, nonatomic) NSMutableDictionary *textAttributes; -/// The \c NSAttributedString attributes to apply to the icons within the text. +/// The `NSAttributedString` attributes to apply to the icons within the text. /// Defaults to a baseline offset of -4.0. @property (strong, nonatomic) NSMutableDictionary *iconAttributes; @@ -113,7 +112,7 @@ @property (nonatomic) NSSize iconSize; /// Whether to hide the / and /Users/ subpaths in displayed paths. -/// This imitates the behaviour of \c NSPathControl et. al. +/// This imitates the behaviour of `NSPathControl` et. al. @property (nonatomic) BOOL hidesSystemRoots; /// Returns an icon-and-label attributed string for the specified path. diff --git a/Boxer/BXWelcomeButtonDraggingDelegate.h b/Boxer/BXWelcomeButtonDraggingDelegate.h index 42ba76752..2141d890d 100644 --- a/Boxer/BXWelcomeButtonDraggingDelegate.h +++ b/Boxer/BXWelcomeButtonDraggingDelegate.h @@ -10,10 +10,10 @@ @class BXWelcomeButton; -/// \c BXWelcomeButtonDraggingDelegate is a basic protocol to let us pass the work of handling +/// `BXWelcomeButtonDraggingDelegate` is a basic protocol to let us pass the work of handling /// welcome button drag-drop events off to an arbitrary delegate (in practice, the window controller.) /// These methods take an additional button: parameter to let the delegate know which button is -/// receiving the drag operation (since the \c NSDraggingInfo protocol offers no way to determine this.) +/// receiving the drag operation (since the `NSDraggingInfo` protocol offers no way to determine this.) @protocol BXWelcomeButtonDraggingDelegate - (NSDragOperation) button: (BXWelcomeButton *)button draggingEntered: (id )sender; diff --git a/Boxer/BXWelcomeWindowController.h b/Boxer/BXWelcomeWindowController.h index 35aba0537..83e4fe2ea 100644 --- a/Boxer/BXWelcomeWindowController.h +++ b/Boxer/BXWelcomeWindowController.h @@ -11,7 +11,7 @@ @class BXWelcomeButton; -/// \c BXWelcomeWindowController manages the welcome window shown when Boxer launches. +/// `BXWelcomeWindowController` manages the welcome window shown when Boxer launches. @interface BXWelcomeWindowController : NSWindowController /// The Open Recent popup button. diff --git a/Boxer/BootlegCoverArt.swift b/Boxer/BootlegCoverArt.swift index 0bbed3b04..89879d448 100644 --- a/Boxer/BootlegCoverArt.swift +++ b/Boxer/BootlegCoverArt.swift @@ -9,6 +9,7 @@ import Cocoa extension BXBootlegCoverArt { + /// Returns a cover art image representation from the instance's title rendered at the specified size, but only on a scale of *1*. func representation(for iconSize: NSSize) -> NSImageRep { return representation(for: iconSize, scale: 1) } @@ -32,19 +33,14 @@ class JewelCase : NSObject, BXBootlegCoverArt { let topLayer = type(of: self).topLayer(for: iconSize) let textRegion = type(of: self).textRegion(for: frame) - if let baseLayer { - baseLayer.draw(in: frame, from: .zero, operation: .sourceOver, fraction: 1) - } + baseLayer?.draw(in: frame, from: .zero, operation: .sourceOver, fraction: 1) if !textRegion.isEmpty { let textAttributes = type(of: self).textAttributes(for: iconSize) - (title as NSString).draw(in: textRegion, withAttributes: textAttributes) - //TODO: use title.draw(with: textRegion, attributes: textAttributes) + title.draw(with: textRegion, attributes: textAttributes, context: nil) } - if let topLayer { - topLayer.draw(in: frame, from: .zero, operation: .sourceOver, fraction: 1) - } + topLayer?.draw(in: frame, from: .zero, operation: .sourceOver, fraction: 1) } final func representation(for iconSize: NSSize, scale: CGFloat) -> NSImageRep { @@ -65,15 +61,15 @@ class JewelCase : NSObject, BXBootlegCoverArt { final func coverArt() -> NSImage { let coverArt = NSImage() coverArt.addRepresentation(representation(for: NSSize(width: 512, height: 512), scale: 2)) - coverArt.addRepresentation(representation(for: NSSize(width: 512, height: 512), scale: 1)) + coverArt.addRepresentation(representation(for: NSSize(width: 512, height: 512))) coverArt.addRepresentation(representation(for: NSSize(width: 256, height: 256), scale: 2)) - coverArt.addRepresentation(representation(for: NSSize(width: 256, height: 256), scale: 1)) + coverArt.addRepresentation(representation(for: NSSize(width: 256, height: 256))) coverArt.addRepresentation(representation(for: NSSize(width: 128, height: 128), scale: 2)) - coverArt.addRepresentation(representation(for: NSSize(width: 128, height: 128), scale: 1)) + coverArt.addRepresentation(representation(for: NSSize(width: 128, height: 128))) coverArt.addRepresentation(representation(for: NSSize(width: 32, height: 32), scale: 2)) - coverArt.addRepresentation(representation(for: NSSize(width: 32, height: 32), scale: 1)) + coverArt.addRepresentation(representation(for: NSSize(width: 32, height: 32))) coverArt.addRepresentation(representation(for: NSSize(width: 16, height: 16), scale: 2)) - coverArt.addRepresentation(representation(for: NSSize(width: 16, height: 16), scale: 1)) + coverArt.addRepresentation(representation(for: NSSize(width: 16, height: 16))) return coverArt } diff --git a/Boxer/DOS window/BXDOSWindow.h b/Boxer/DOS window/BXDOSWindow.h index 7c860010c..e8a589b41 100644 --- a/Boxer/DOS window/BXDOSWindow.h +++ b/Boxer/DOS window/BXDOSWindow.h @@ -14,8 +14,8 @@ @class BXDOSWindowController; -/// \c BXDOSWindow is the main window for a DOS session. This class is heavily reliant on -/// \c BXDOSWindowController and exists mainly just to override NSWindow's default window sizing +/// `BXDOSWindow` is the main window for a DOS session. This class is heavily reliant on +/// `BXDOSWindowController` and exists mainly just to override `NSWindow`'s default window sizing /// and constraining methods. @interface BXDOSWindow : ADBFullscreenCapableWindow diff --git a/Boxer/DOS window/BXDOSWindowBackgroundView.h b/Boxer/DOS window/BXDOSWindowBackgroundView.h index 3a6bb58a9..69e3fab9e 100644 --- a/Boxer/DOS window/BXDOSWindowBackgroundView.h +++ b/Boxer/DOS window/BXDOSWindowBackgroundView.h @@ -7,7 +7,7 @@ #import -/// BXDOSWindowBackgroundView simply renders the badged grey gradient background of the DOS window. +/// `BXDOSWindowBackgroundView` simply renders the badged grey gradient background of the DOS window. @interface BXDOSWindowBackgroundView : NSView @end diff --git a/Boxer/DOS window/BXDOSWindowController.h b/Boxer/DOS window/BXDOSWindowController.h index ec1edc9f9..12c0c80d2 100644 --- a/Boxer/DOS window/BXDOSWindowController.h +++ b/Boxer/DOS window/BXDOSWindowController.h @@ -45,10 +45,10 @@ typedef NS_ENUM(NSInteger, BXDOSWindowPanel) { @protocol BXFrameRenderingView; /// Produced by our rendering view when it begins/ends a live resize operation. -extern NSString * const BXViewWillLiveResizeNotification; -extern NSString * const BXViewDidLiveResizeNotification; +extern NSNotificationName const BXViewWillLiveResizeNotification; +extern NSNotificationName const BXViewDidLiveResizeNotification; -/// \c BXDOSWindowController manages a session window and its dependent views and view controllers. +/// `BXDOSWindowController` manages a session window and its dependent views and view controllers. /// Besides the usual window-controller responsibilities, it handles switching to and from fullscreen /// and passing frames to the emulator to the rendering view. @interface BXDOSWindowController : NSWindowController @@ -170,8 +170,9 @@ extern NSString * const BXViewDidLiveResizeNotification; /// Toggle the emulator's active rendering filter. - (IBAction) toggleRenderingStyle: (id)sender; -/// Increase/decrease the draw size of the fullscreen window. +/// Increase the draw size of the fullscreen window. - (IBAction) incrementFullscreenSize: (id)sender; +/// Decrease the draw size of the fullscreen window. - (IBAction) decrementFullscreenSize: (id)sender; #pragma mark - diff --git a/Boxer/DOS window/BXDOSWindowControllerLion.h b/Boxer/DOS window/BXDOSWindowControllerLion.h index 1653757f6..b50332ead 100644 --- a/Boxer/DOS window/BXDOSWindowControllerLion.h +++ b/Boxer/DOS window/BXDOSWindowControllerLion.h @@ -8,7 +8,7 @@ #import "BXDOSWindowController.h" -/// \c BXDOSWindowControllerLion is a subclass of \c BXDOSWindowController that implements Lion's +/// `BXDOSWindowControllerLion` is a subclass of `BXDOSWindowController` that implements Lion's /// new fullscreen and window restoration APIs. @interface BXDOSWindowControllerLion : BXDOSWindowController { diff --git a/Boxer/DOS window/BXDOSWindowControllerPrivate.h b/Boxer/DOS window/BXDOSWindowControllerPrivate.h index ac2807384..332f533fa 100644 --- a/Boxer/DOS window/BXDOSWindowControllerPrivate.h +++ b/Boxer/DOS window/BXDOSWindowControllerPrivate.h @@ -19,7 +19,7 @@ #pragma mark Private method declarations -// BXDOSWindowControllerPrivate defines the private interface and constants +/// BXDOSWindowControllerPrivate defines the private interface and constants /// for BXDOSWindowController and its subclasses. @interface BXDOSWindowController () @@ -27,7 +27,7 @@ /// (which clears the window's frame name temporarily so that the fullscreen frame isn't saved.) @property (copy, nonatomic) NSString *autosaveNameBeforeFullScreen; -/// Returns \c YES if the window is in the process of resizing itself. +/// Returns `YES` if the window is in the process of resizing itself. @property (readonly, nonatomic) BOOL isResizing; /// Returns the size that the rendering view would currently be *if it were in windowed mode.* @@ -35,7 +35,7 @@ @property (readonly, nonatomic) NSSize windowedRenderingViewSize; /// The maximum size at which the rendering view should render. -/// This will return \c NSZeroSize while in windowed mode or when no \c maxFullscreenViewportSize has been set. +/// This will return `NSZeroSize` while in windowed mode or when no `-maxFullscreenViewportSize` has been set. @property (readonly, nonatomic) NSSize maxViewportSizeUIBinding; /// Whether the fullscreen size is at its minimum/maximum extents. @@ -44,7 +44,7 @@ @property (readonly, nonatomic) BOOL fullscreenSizeAtMaximum; /// Whether the viewport will fill the screen in fullscreen mode. -/// Will be YES if \c maxFullscreenViewportSize is NSZeroSize. +/// Will be `YES` if `-maxFullscreenViewportSize` is `NSZeroSize`. @property (readonly, nonatomic) BOOL fullscreenViewportFillsCanvas; /// The minimum size to which the fullscreen viewport can be set. @@ -78,7 +78,7 @@ animate: (BOOL)performAnimation; /// Resize the window if needed to accomodate the specified frame. -/// Returns YES if the window was resized, NO if the size remained the same. +/// Returns `YES` if the window was resized, `NO` if the size remained the same. - (BOOL) _resizeToAccommodateFrame: (BXVideoFrame *)frame; /// Returns the view size that should be used for rendering the specified frame. @@ -92,7 +92,7 @@ - (void) _slideView: (NSView *)view shown: (BOOL)show animate: (BOOL)animate; /// Whether aspect-ratio correction should be applied to the specified frame. -/// Will return \c NO for text-only frames, \c YES otherwise. +/// Will return `NO` for text-only frames, `YES` otherwise. - (BOOL) _shouldCorrectAspectRatioOfFrame: (BXVideoFrame *)frame; /// Returns the next suitable fullscreen viewport size that's above/below the specified size. diff --git a/Boxer/DOS window/BXInputController+BXJoystickInput.h b/Boxer/DOS window/BXInputController+BXJoystickInput.h index 57798f01f..e2618fa9c 100644 --- a/Boxer/DOS window/BXInputController+BXJoystickInput.h +++ b/Boxer/DOS window/BXInputController+BXJoystickInput.h @@ -10,18 +10,18 @@ #import "BXEmulatedJoystick.h" #import "ADBHIDEvent.h" -/// \c BXJoysticks extends \c BXInputController with delegate methods for handling HID joystick input +/// `BXJoystickInput` extends `BXInputController` with delegate methods for handling HID joystick input /// from BXJoystickController. These are translated into emulated joystick responses and passed /// to BXInputHandler. @interface BXInputController (BXJoystickInput) -/// Whether to use the standard (BXGameportPollBasedTiming) or strict (BXGameportClockBasedTiming) gameport timing mode. +/// Whether to use the standard (`BXGameportPollBasedTiming`) or strict (`BXGameportClockBasedTiming`) gameport timing mode. @property (assign, nonatomic) BOOL strictGameportTiming; -/// Which joystick type to use if supported, specified as a class conforming to the \c BXEmulatedJoystick protocol. +/// Which joystick type to use if supported, specified as a class conforming to the `BXEmulatedJoystick` protocol. @property (copy, nonatomic) Class preferredJoystickType; -/// The joystick types available to choose from, represented as an array of BXEmulatedJoystick-conforming classes. +/// The joystick types available to choose from, represented as an array of `BXEmulatedJoystick`-conforming classes. /// Used by the joystick type picker in the Inspector UI. @property (readonly, retain, nonatomic) NSArray *availableJoystickTypes; diff --git a/Boxer/DOS window/BXInputController+BXKeyboardInput.h b/Boxer/DOS window/BXInputController+BXKeyboardInput.h index 7befe236e..2b9d13823 100644 --- a/Boxer/DOS window/BXInputController+BXKeyboardInput.h +++ b/Boxer/DOS window/BXInputController+BXKeyboardInput.h @@ -8,7 +8,7 @@ #import "BXInputController.h" -/// The \c BXKeyboardInput category handles BXInputController's keyboard event responses +/// The `BXKeyboardInput` category handles `BXInputController`'s keyboard event responses /// and simulated keyboard actions. @interface BXInputController (BXKeyboardInput) diff --git a/Boxer/DOS window/BXInputController.h b/Boxer/DOS window/BXInputController.h index 7c0e1c624..9dba00976 100644 --- a/Boxer/DOS window/BXInputController.h +++ b/Boxer/DOS window/BXInputController.h @@ -14,10 +14,11 @@ @class BXSession; @class DDHidJoystick; -/// BXInputController processes keyboard and mouse events received by its view and turns them +/// `BXInputController` processes keyboard and mouse events received by its view and turns them /// into input commands to the emulator's own input handler (which for convenience is set as the /// controller's representedObject). -/// It also manages mouse locking and the appearance and behaviour of the OS X mouse cursor. +/// +/// It also manages mouse locking and the appearance and behaviour of the macOS mouse cursor. @interface BXInputController : NSViewController { BXCursorFadeAnimation *_cursorFade; @@ -40,7 +41,7 @@ BXMouseButtonMask _simulatedMouseButtons; - /// Which OSX virtual keycodes were pressed with a modifier, causing + /// Which macOS virtual keycodes were pressed with a modifier, causing /// them to send a different key than usual. Used for releasing /// simulated keys upon key-up. BOOL _modifiedKeys[BXMaxSystemKeyCode]; @@ -91,15 +92,15 @@ /// Called when the cursor needs updating outside of the standard NSResponder event mechanisms. - (void) syncCursor; -/// Called by \c BXDOSWindowController whenever the view loses keyboard focus. +/// Called by `BXDOSWindowController` whenever the view loses keyboard focus. - (void) didResignKey; -/// Called by \c BXDOSWindowController whenever the view regains keyboard focus. +/// Called by `BXDOSWindowController` whenever the view regains keyboard focus. - (void) didBecomeKey; /// Applies the specified mouse-lock state. -/// If force is NO, the mouse will not be locked if canLockMouse returns NO. -/// If force is YES, it will be locked regardless. +/// If `force` is `NO`, the mouse will not be locked if `-canLockMouse` returns `NO`. +/// If `force` is `YES`, it will be locked regardless. - (void) setMouseLocked: (BOOL)locked force: (BOOL)force; diff --git a/Boxer/DOS window/BXInputControllerPrivate.h b/Boxer/DOS window/BXInputControllerPrivate.h index 602db6d03..aeff8bf2a 100644 --- a/Boxer/DOS window/BXInputControllerPrivate.h +++ b/Boxer/DOS window/BXInputControllerPrivate.h @@ -137,7 +137,7 @@ void _inputSourceChanged(CFNotificationCenterRef center, @interface BXInputController (BXKeyboardInputInternals) -/// Resynchronises the DOS keyboard layout with the current OS X text-input source. +/// Resynchronises the DOS keyboard layout with the current macOS text-input source. - (void) _syncKeyboardLayout; /// Resynchronises the current state of the Shift, Ctrl, Alt, CapsLock etc. @@ -148,7 +148,7 @@ void _inputSourceChanged(CFNotificationCenterRef center, - (BXDOSKeyCode) _DOSKeyCodeForSystemKeyCode: (CGKeyCode)keyCode; /// Returns the DOS keycode constant that should be simulated when the specified -/// OSX keycode is pressed along with the Fn key. +/// macOS keycode is pressed along with the Fn key. - (BXDOSKeyCode) _simulatedNumpadKeyCodeForSystemKeyCode: (CGKeyCode)keyCode; /// Called whenever the emulated keyboard's numlock state changes. diff --git a/Boxer/DOS window/BXInputView.h b/Boxer/DOS window/BXInputView.h index 5ee093b58..f80e696d3 100644 --- a/Boxer/DOS window/BXInputView.h +++ b/Boxer/DOS window/BXInputView.h @@ -8,6 +8,6 @@ #import -/// \c BXInputView tracks keyboard and mouse input and passes them to its BXInputController. +/// `BXInputView` tracks keyboard and mouse input and passes them to its BXInputController. @interface BXInputView : NSView @end diff --git a/Boxer/DOS window/BXLaunchPanelController.h b/Boxer/DOS window/BXLaunchPanelController.h index da0c63d4e..387cddc88 100644 --- a/Boxer/DOS window/BXLaunchPanelController.h +++ b/Boxer/DOS window/BXLaunchPanelController.h @@ -38,7 +38,7 @@ - (IBAction) enterSearchText: (NSSearchField *)sender; -/// Called by \c BXDOSWindowController when it is about to switch to/away from the launcher panel. +/// Called by `BXDOSWindowController` when it is about to switch to/away from the launcher panel. /// Causes it to (re-)populate its program list. - (void) willShowPanel; - (void) didHidePanel; @@ -59,13 +59,15 @@ @interface BXLauncherItem : BXCollectionItem @property (weak, nonatomic) IBOutlet id delegate; @property (assign, nonatomic, getter=isLaunchable) BOOL launchable; -@property (strong, atomic) IBOutlet NSMenu *menu; //The context menu to display for this item. +/// The context menu to display for this item. +@property (strong, atomic) IBOutlet NSMenu *menu; - (IBAction) openItemInDOS: (id)sender; - (IBAction) revealItemInFinder: (id)sender; - (IBAction) removeItem: (id)sender; /// Returns the menu which the specified view should display when right-clicked. +/// /// Allows the launcher item to customise the menu based on the contents of its represented object. - (NSMenu *) menuForView: (BXLauncherItemView *)view; @end diff --git a/Boxer/DOS window/BXProgramPanel.h b/Boxer/DOS window/BXProgramPanel.h index 004e22ee5..47f577c57 100644 --- a/Boxer/DOS window/BXProgramPanel.h +++ b/Boxer/DOS window/BXProgramPanel.h @@ -17,7 +17,7 @@ NS_ASSUME_NONNULL_BEGIN //Interface Builder tags -enum { +NS_ENUM(NSInteger) { BXProgramPanelTitle = 1, BXProgramPanelDefaultToggle = 2, BXProgramPanelHide = 3, diff --git a/Boxer/DOS window/BXProgramPanelController.h b/Boxer/DOS window/BXProgramPanelController.h index b72d1199a..4c7d01097 100644 --- a/Boxer/DOS window/BXProgramPanelController.h +++ b/Boxer/DOS window/BXProgramPanelController.h @@ -10,7 +10,7 @@ @class BXSession; -/// \c BXProgramPanelController manages the program picker panel inside the session window. It is +/// `BXProgramPanelController` manages the program picker panel inside the session window. It is /// responsible for populating the program selection and toggling which picker interface is shown /// (picker, default program toggle, no programs notice) based on the state of the session. /// @@ -71,7 +71,7 @@ __deprecated - (void) syncPanelExecutables; /// Whether we can set the currently-active program to be the default gamebox target. -/// Will be \c NO if there's no active program, there's no gamebox, or the active program is outside the gamebox. +/// Will be `NO` if there's no active program, there's no gamebox, or the active program is outside the gamebox. - (BOOL) canSetActiveProgramToDefault; diff --git a/Boxer/Documentation Panel/BXDocumentationBrowser.h b/Boxer/Documentation Panel/BXDocumentationBrowser.h index 13b8e61ae..c1ede00be 100644 --- a/Boxer/Documentation Panel/BXDocumentationBrowser.h +++ b/Boxer/Documentation Panel/BXDocumentationBrowser.h @@ -19,7 +19,7 @@ #pragma mark - Properties -/// The delegate to which we will send \c BXDocumentationBrowserDelegate messages. +/// The delegate to which we will send `BXDocumentationBrowserDelegate` messages. @property (weak, nonatomic) IBOutlet id delegate; /// The scrolling wrapper in which our documenation list is displayed. @@ -34,7 +34,7 @@ /// The collection view in which our documentation will be displayed. @property (strong, nonatomic) IBOutlet BXDocumentationList *documentationList; -/// An array of NSURLs for the documentation files included in this gamebox. +/// An array of `NSURL`s for the documentation files included in this gamebox. /// This is mapped directly to the documentation URLs reported by the gamebox. @property (readonly, copy, nonatomic) NSArray *documentationURLs; @@ -67,6 +67,8 @@ /// Returns a newly-created BXDocumentationListController instance /// whose UI is loaded from DocumentationList.xib. + (instancetype) browserForSession: (BXSession *)session; +/// Returns a newly-created BXDocumentationListController instance +/// whose UI is loaded from DocumentationList.xib. - (instancetype) initWithSession: (BXSession *)session; @@ -76,9 +78,11 @@ - (IBAction) revealSelectedDocumentationItemsInFinder: (id)sender; - (IBAction) trashSelectedDocumentationItems: (id)sender; -/// Helper methods for adding/removing documentation items. -/// These will register undo actions and will present error sheets if importing/removal fails. +/// Helper method for removing documentation items. +/// These will register undo actions and will present error sheets if removal fails. - (BOOL) removeDocumentationURLs: (NSArray *)URLs; +/// Helper method for adding documentation items. +/// These will register undo actions and will present error sheets if importing fails. - (BOOL) importDocumentationURLs: (NSArray *)URLs; @@ -96,7 +100,7 @@ @end -/// The \c BXDocumentationPreviews category expands BXDocumentationListController to allow documentation to be shown in a QuickLook preview panel. +/// The `BXDocumentationPreviews` category expands BXDocumentationListController to allow documentation to be shown in a QuickLook preview panel. @interface BXDocumentationBrowser (BXDocumentationPreviews) /// Displays a QuickLook preview panel for the specified documentation items. @@ -122,12 +126,12 @@ - (void) documentationBrowser: (BXDocumentationBrowser *)browser didRevealURLs: (NSArray *)URLs; /// Called when the browser has encountered an error that it cannot deal with and will present it. -/// This is analoguous to willPresentError:, and likewise you can return a different error to customize +/// This is analoguous to `-willPresentError:`, and likewise you can return a different error to customize /// the error that will be displayed. - (NSError *) documentationBrowser: (BXDocumentationBrowser *)browser willPresentError: (NSError *)error; /// Called when the browser wants to present an error, to return the window in which it should present the error modally. -/// If this returns nil, or is unimplemented, the error will be presented as application-modal instead. +/// If this returns `nil`, or is unimplemented, the error will be presented as application-modal instead. - (NSWindow *) documentationBrowser: (BXDocumentationBrowser *)browser windowForModalError: (NSError *)error; /// Called just before the browser updates with new URLs. At this point the browser's documentationURLs property, @@ -177,7 +181,7 @@ /// Returns the specified width rounded up to match cleanly to one of our own possible widths. /// -/// Used by BXDocumentationBrowser idealContentSizeForNumberOfItems: to ensure that it shinkwraps +/// Used by `-[BXDocumentationBrowser idealContentSizeForNumberOfItems:]` to ensure that it shinkwraps /// the browser to a size that can cleanly accommodate each column of documentation. - (CGFloat) snappedWidthForTargetWidth: (CGFloat)targetWidth; diff --git a/Boxer/Documentation Panel/BXDocumentationPanelController.h b/Boxer/Documentation Panel/BXDocumentationPanelController.h index 3ec99589e..390559f12 100644 --- a/Boxer/Documentation Panel/BXDocumentationPanelController.h +++ b/Boxer/Documentation Panel/BXDocumentationPanelController.h @@ -19,8 +19,8 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Properties /// The session whose documents are being displayed in the panel. -// FIXME: This may be introducing a memory leak by holding a strong reference -@property (strong, nonatomic, nullable) BXSession *session; +@property (strong, nonatomic, nullable) BXSession *session; // FIXME: This may be introducing a memory leak by holding a strong reference + /// Whether the panel is currently visible, either as a popover or as a window. @property (readonly, nonatomic, getter=isShown) BOOL shown; @@ -28,7 +28,7 @@ NS_ASSUME_NONNULL_BEGIN /// The maximum size we permit the popover to get. @property (assign, nonatomic) NSSize maxPopoverSize; -/// Returns whether popovers are available. This will return NO on 10.6. +/// Returns whether popovers are available. This will return `NO` on 10.6. @property (class, readonly) BOOL supportsPopover; @@ -40,7 +40,7 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark - Display methods /// Displays the documentation browser in a popover at the specified location. -/// On 10.6, which does not support popovers, this will call displayInWindow instead. +/// On 10.6, which does not support popovers, this will call `-displayInWindow` instead. - (void) displayForSession: (BXSession *)session inPopoverRelativeToRect: (NSRect)positioningRect ofView: (NSView *)positioningView diff --git a/Boxer/Input/BXOutputBinding.h b/Boxer/Input/BXOutputBinding.h index 0bc621627..22516fda1 100644 --- a/Boxer/Input/BXOutputBinding.h +++ b/Boxer/Input/BXOutputBinding.h @@ -35,7 +35,7 @@ typedef NS_ENUM(NSInteger, BXAxisPolarity) { #pragma mark - Protocols -/// @c BXOutputBindings take a scalar input value from 0.0 to 1.0 and trigger a signal on an emulated input device: +/// `BXOutputBindings` take a scalar input value from 0.0 to 1.0 and trigger a signal on an emulated input device: /// e.g. an emulated joystick or keyboard. @protocol BXOutputBinding diff --git a/Boxer/Inspector Panel/BXCoverArtWell.h b/Boxer/Inspector Panel/BXCoverArtWell.h index eafb3cefe..7d3505045 100644 --- a/Boxer/Inspector Panel/BXCoverArtWell.h +++ b/Boxer/Inspector Panel/BXCoverArtWell.h @@ -8,10 +8,10 @@ #import -/// \c BXCoverArtWell is a custom image well for dropping game artwork into the Inspector panel. +/// `BXCoverArtWell` is a custom image well for dropping game artwork into the Inspector panel. /// It displays the cover art image of the current gamebox, or a dashed grey drop region indicator /// if the gamebox has no cover art. It converts dropped/pasted images into the Boxer cover-art style -/// using BXCoverArt. +/// using `BXCoverArt`. /// /// IB note: this view enlarges itself slightly from the size set in Interface Builder, in order to /// accomodate its custom focus ring without clipping. (We use a custom focus ring because we're a diff --git a/Boxer/Inspector Panel/BXDriveItem.h b/Boxer/Inspector Panel/BXDriveItem.h index fbfb30734..3a8ad0146 100644 --- a/Boxer/Inspector Panel/BXDriveItem.h +++ b/Boxer/Inspector Panel/BXDriveItem.h @@ -8,8 +8,8 @@ #import "BXCollectionItemView.h" @class BXDrive; -/// BXDriveItem represents each drive in the list and acts -/// as a view controller for its corresponding BXDriveItemView. +/// `BXDriveItem` represents each drive in the list and acts +/// as a view controller for its corresponding `BXDriveItemView`. @interface BXDriveItem : BXCollectionItem #pragma mark - Outlet properties @@ -26,7 +26,7 @@ #pragma mark - Description properties -/// The drive to which this item corresponds. Derived automatically from representedObject. +/// The drive to which this item corresponds. Derived automatically from `-representedObject`. @property (strong, readonly, nonatomic) BXDrive *drive; /// The icon to display for the drive we represent. @@ -62,7 +62,7 @@ #pragma mark - Notifications -/// Import notifications dispatched by BXDrivePanelController, +/// Import notifications dispatched by `BXDrivePanelController`, /// to the drive item for the drive being imported. - (void) driveImportWillStart: (NSNotification *)notification; - (void) driveImportInProgress: (NSNotification *)notification; diff --git a/Boxer/Inspector Panel/BXDriveList.h b/Boxer/Inspector Panel/BXDriveList.h index 63212ee70..7804ab657 100644 --- a/Boxer/Inspector Panel/BXDriveList.h +++ b/Boxer/Inspector Panel/BXDriveList.h @@ -14,7 +14,7 @@ @class BXDriveItem; @class BXDriveItemView; -/// \c BXDriveList represents the currently-mounted DOS drives in the Boxer inspector panel. It is +/// `BXDriveList` represents the currently-mounted DOS drives in the Boxer inspector panel. It is /// a custom subclass of the standard Cocoa collection view to implement drag operations for drives. @interface BXDriveList : NSCollectionView diff --git a/Boxer/Inspector Panel/BXDrivePanelController.h b/Boxer/Inspector Panel/BXDrivePanelController.h index 8d00f2801..b7ee5c239 100644 --- a/Boxer/Inspector Panel/BXDrivePanelController.h +++ b/Boxer/Inspector Panel/BXDrivePanelController.h @@ -13,7 +13,7 @@ @class BXDriveList; @class BXDrive; -/// \c BXDrivePanelController manages the Drives panel of the Inspector window. +/// `BXDrivePanelController` manages the Drives panel of the Inspector window. @interface BXDrivePanelController : NSViewController #pragma mark - @@ -49,7 +49,7 @@ - (IBAction) openSelectedDrivesInDOS: (id)sender; /// Mount/unmount the selected drives in DOS. Will call mountSelectedDrives: if all selected -/// drives are unmounted, or unmountSelectedDrives: if one or more selected drives is mounted. +/// drives are unmounted, or `-unmountSelectedDrives:` if one or more selected drives is mounted. - (IBAction) toggleSelectedDrives: (id)sender; /// Mount the selected drives in DOS. diff --git a/Boxer/Inspector Panel/BXGameboxPanelController.h b/Boxer/Inspector Panel/BXGameboxPanelController.h index 70bf644ae..c5cde014e 100644 --- a/Boxer/Inspector Panel/BXGameboxPanelController.h +++ b/Boxer/Inspector Panel/BXGameboxPanelController.h @@ -10,7 +10,7 @@ @class BXSession; -/// \c BXGameboxPanelController manages the gamebox panel of the Inspector window. Its primary concern +/// `BXGameboxPanelController` manages the gamebox panel of the Inspector window. Its primary concern /// is the choose-a-default-program popup button: it is responsible for populating the popup button /// menu with the available programs in the current gamebox (if any), and synchronising its selection /// with the default program of the gamebox. @@ -29,7 +29,7 @@ /// Currently unused - intended for a button to sit alongside the program popup selector. - (IBAction) launchDefaultProgram: (id)sender; -/// Shows a standard OS X open panel for choosing an executable file from Finder. +/// Shows a standard macOS open panel for choosing an executable file from Finder. - (IBAction) showProgramChooserPanel: (id)sender; /// Called after choosing a new program from the file picker. Adds a new item for that URL diff --git a/Boxer/Inspector Panel/BXInspectorController.h b/Boxer/Inspector Panel/BXInspectorController.h index b26d9e5a7..1eb9a625a 100644 --- a/Boxer/Inspector Panel/BXInspectorController.h +++ b/Boxer/Inspector Panel/BXInspectorController.h @@ -19,7 +19,7 @@ NS_ENUM(NSInteger) { @class BXDriveList; -/// \c BXInspectorController manages the Boxer inspector panel. It is responsible for displaying and +/// `BXInspectorController` manages the Boxer inspector panel. It is responsible for displaying and /// toggling the tabs of the panel. @interface BXInspectorController : ADBTabbedWindowController { @@ -49,7 +49,7 @@ NS_ENUM(NSInteger) { - (IBAction) showInactiveJoystickPanelHelp: (id)sender; /// Temporarily hides the panel if it is currently visible: -/// It can then be unhidden with revealIfHidden. +/// It can then be unhidden with `-revealIfHidden`. /// This is used to temporarily suppress the inspector panel while the mouse is locked. - (void) hideIfVisible; - (void) revealIfHidden; diff --git a/Boxer/MT32LCDDisplay.swift b/Boxer/MT32LCDDisplay.swift index da4de6a79..6a21a4916 100644 --- a/Boxer/MT32LCDDisplay.swift +++ b/Boxer/MT32LCDDisplay.swift @@ -8,7 +8,7 @@ import Cocoa -/// BXMT32LCDDisplay imitates, as the name suggests, the LCD display on a Roland MT-32 Sound Module. +/// `MT32LCDDisplay` imitates, as the name suggests, the LCD display on a Roland MT-32 Sound Module. /// It is used for displaying messages sent by the games to the emulated MT-32. (Many Sierra games /// would send cheeky messages to it on startup.) /// diff --git a/Other Sources/ADBToolkit/ADBOperation.h b/Other Sources/ADBToolkit/ADBOperation.h index cd0179004..fdd2f5318 100644 --- a/Other Sources/ADBToolkit/ADBOperation.h +++ b/Other Sources/ADBToolkit/ADBOperation.h @@ -101,7 +101,7 @@ extern NSString * const ADBOperationIndeterminateKey; @property (weak, nullable) id delegate; /// The callback methods that will be called on the delegate for progress notifications. -/// These default to @c ADBOperationDelegate operationInProgress:, @c operationDidFinish: etc. +/// These default to `ADBOperationDelegate` `operationInProgress:`, `operationDidFinish:` etc. /// and must have the same signatures as those methods. @property (assign) SEL willStartSelector; @property (assign) SEL inProgressSelector; @@ -109,11 +109,11 @@ extern NSString * const ADBOperationIndeterminateKey; @property (assign) SEL didFinishSelector; /// Arbitrary context info for this operation. Included in notification dictionaries -/// for controlling contexts to use. Note that this is an NSObject and will be retained. +/// for controlling contexts to use. Note that this is an `NSObject` and will be retained. @property (strong, nullable) id contextInfo; -/// Whether delegate and \c NSNotificationCenter notifications should be sent on the main -/// thread or on the operation's current thread. Defaults to \c YES (the main thread). +/// Whether delegate and `NSNotificationCenter` notifications should be sent on the main +/// thread or on the operation's current thread. Defaults to `YES` (the main thread). @property (assign) BOOL notifiesOnMainThread; #pragma mark - @@ -135,13 +135,14 @@ extern NSString * const ADBOperationIndeterminateKey; /// Whether the operation has succeeeded or failed: only applicable once the operation /// finishes, though it can be called at any time. -/// In the base implementation, this will return \c NO if the operation has generated -/// an error, or \c YES otherwise (even if the operation has not yet finished.) +/// +/// In the base implementation, this will return `NO` if the operation has generated +/// an error, or `YES` otherwise (even if the operation has not yet finished.) /// This can be overridden by subclasses. @property (readonly) BOOL succeeded; /// Any showstopping error that occurred when performing the operation. -/// If this is set, succeeded will be NO. +/// If this is set, succeeded will be `NO`. @property (strong, nullable) NSError *error; @end