Why does Apple's documentation only show the properties and method signatures but not the actual code?

时间:2016-08-31 16:59:53

标签: ios swift xcode apple-documentation

I'm exploring Apple's documentation and would like to understand how classes such as UIApplication do what they do under the hood however if you command click "UIApplication", Xcode only shows UIApplication's properties and method signatures but not the actual code inside the methods. I figured this would be valuable information to know if we could see what's going on inside of Apple's provided classes but why isn't it available for us to know or see?

For example, here is what's shown if you command click UIApplication:

public class UIApplication : UIResponder {

    public class func sharedApplication() -> UIApplication

    unowned(unsafe) public var delegate: UIApplicationDelegate?

    public func beginIgnoringInteractionEvents() // nested. set should be set during animations & transitions to ignore touch and other events
    public func endIgnoringInteractionEvents()
    public func isIgnoringInteractionEvents() -> Bool // returns YES if we are at least one deep in ignoring events

    public var idleTimerDisabled: Bool // default is NO

    public func openURL(url: NSURL) -> Bool
    @available(iOS 3.0, *)
    public func canOpenURL(url: NSURL) -> Bool

    public func sendEvent(event: UIEvent)

    public var keyWindow: UIWindow? { get }
    public var windows: [UIWindow] { get }

    public func sendAction(action: Selector, to target: AnyObject?, from sender: AnyObject?, forEvent event: UIEvent?) -> Bool

    public var networkActivityIndicatorVisible: Bool // showing network spinning gear in status bar. default is NO

    // default is UIStatusBarStyleDefault

    // The system only calls this method if the application delegate has not
    // implemented the delegate equivalent. It returns the orientations specified by
    // the application's info.plist. If no supported interface orientations were
    // specified it will return UIInterfaceOrientationMaskAll on an iPad and
    // UIInterfaceOrientationMaskAllButUpsideDown on a phone.  The return value
    // should be one of the UIInterfaceOrientationMask values which indicates the
    // orientations supported by this application.
    @available(iOS 6.0, *)
    public func supportedInterfaceOrientationsForWindow(window: UIWindow?) -> UIInterfaceOrientationMask

    public var statusBarOrientationAnimationDuration: NSTimeInterval { get } // Returns the animation duration for the status bar during a 90 degree orientation change.  It should be doubled for a 180 degree orientation change.
    public var statusBarFrame: CGRect { get } // returns CGRectZero if the status bar is hidden

    public var applicationIconBadgeNumber: Int // set to 0 to hide. default is 0. In iOS 8.0 and later, your application must register for user notifications using -[UIApplication registerUserNotificationSettings:] before being able to set the icon badge.

    @available(iOS 3.0, *)
    public var applicationSupportsShakeToEdit: Bool

    @available(iOS 4.0, *)
    public var applicationState: UIApplicationState { get }
    @available(iOS 4.0, *)
    public var backgroundTimeRemaining: NSTimeInterval { get }

    @available(iOS 4.0, *)
    public func beginBackgroundTaskWithExpirationHandler(handler: (() -> Void)?) -> UIBackgroundTaskIdentifier
    @available(iOS 7.0, *)
    public func beginBackgroundTaskWithName(taskName: String?, expirationHandler handler: (() -> Void)?) -> UIBackgroundTaskIdentifier
    @available(iOS 4.0, *)
    public func endBackgroundTask(identifier: UIBackgroundTaskIdentifier)

    /*! The system guarantees that it will not wake up your application for a background fetch more
        frequently than the interval provided. Set to UIApplicationBackgroundFetchIntervalMinimum to be
        woken as frequently as the system desires, or to UIApplicationBackgroundFetchIntervalNever (the
        default) to never be woken for a background fetch.

        This setter will have no effect unless your application has the "fetch" 
        UIBackgroundMode. See the UIApplicationDelegate method
        `application:performFetchWithCompletionHandler:` for more. */
    @available(iOS 7.0, *)
    public func setMinimumBackgroundFetchInterval(minimumBackgroundFetchInterval: NSTimeInterval)

    /*! When background refresh is available for an application, it may launched or resumed in the background to handle significant
        location changes, remote notifications, background fetches, etc. Observe UIApplicationBackgroundRefreshStatusDidChangeNotification to
        be notified of changes. */
    @available(iOS 7.0, *)
    public var backgroundRefreshStatus: UIBackgroundRefreshStatus { get }

    @available(iOS 4.0, *)
    public var protectedDataAvailable: Bool { get }

    @available(iOS 5.0, *)
    public var userInterfaceLayoutDirection: UIUserInterfaceLayoutDirection { get }

    // Return the size category
    @available(iOS 7.0, *)
    public var preferredContentSizeCategory: String { get }
}

1 个答案:

答案 0 :(得分:3)

This is common practice when providing someone with API to your product (in this case Apple's SDKs). Implementation details are up to creator and you don't need to know how things work on the inside. All you need to know are the tools which will allow to work with their product and those tools are called API.

API on wiki

Implementation itself can and often does change and API is designed in such way that these changes won't disrupt or break your application. Seeing the code behind could lead you to incorrect assumptions and/or bad practices. Not to mention that it is often proprietary and not really intended for public eyes.

EDIT:

You aren't concerned with implementation, because you are not the one writing it. Apple creates implementation, you just use whatever they make behind the scenes.

For example, take the beginIgnoringInteractionEvents method. You do not know what exactly happens when you call it. All you know is that once you call it, you will stop getting interaction events. If the do it by simply setting some internal checkForEvents property to false or they remove handler from list of handlers or they recreate entire view hierarchy is up to them, it is completely transparent to you. You don't need to be concerned about internals, you just need to know what the method/property does and it is up to Apple to ensure that it will keep its promise (and you will get disappointed once in a while when you encounter a bug in the behaviour)