docs(CordovaLib): Start filling out DocC comments (#1476)

Author: dpogue

CordovaLib/Classes/Private/Plugins/CDVLaunchScreen/CDVLaunchScreen.m

@@ -21,14 +21,14 @@ Licensed to the Apache Software Foundation (ASF) under one
 
 @implementation CDVLaunchScreen
 
-- (void)show:(CDVInvokedUrlCommand*)command
+- (void)show:(CDVInvokedUrlCommand *)command
 {
-    [self.viewController showLaunchScreen:YES];
+    [self.viewController showSplashScreen:YES];
 }
 
-- (void)hide:(CDVInvokedUrlCommand*)command
+- (void)hide:(CDVInvokedUrlCommand *)command
 {
-    [self.viewController showLaunchScreen:NO];
+    [self.viewController showSplashScreen:NO];
 }
 
 @end

CordovaLib/Classes/Public/CDVCommandQueue.m

@@ -21,6 +21,7 @@ Licensed to the Apache Software Foundation (ASF) under one
 #import <Cordova/CDVCommandQueue.h>
 #import <Cordova/CDVViewController.h>
 #import <Cordova/CDVPlugin.h>
+#import <Cordova/NSMutableArray+QueueAdditions.h>
 #import "CDVCommandDelegateImpl.h"
 #import "CDVJSON_private.h"
 #import "CDVDebug.h"

CordovaLib/Classes/Public/CDVViewController.m

@@ -495,13 +495,13 @@ - (void)onWebViewPageDidLoad:(NSNotification*)notification
         CGFloat splashScreenDelaySetting = [self.settings cordovaFloatSettingForKey:@"SplashScreenDelay" defaultValue:0];
 
         if (splashScreenDelaySetting == 0) {
-            [self showLaunchScreen:NO];
+            [self showSplashScreen:NO];
         } else {
             // Divide by 1000 because config returns milliseconds and NSTimer takes seconds
             CGFloat splashScreenDelay = splashScreenDelaySetting / 1000;
 
             [NSTimer scheduledTimerWithTimeInterval:splashScreenDelay repeats:NO block:^(NSTimer * _Nonnull timer) {
-                [self showLaunchScreen:NO];
+                [self showSplashScreen:NO];
             }];
         }
     }
@@ -719,10 +719,12 @@ - (bool)checkAndReinitViewUrl
 
 #pragma mark - API Methods for Plugins
 
-/**
- Method to be called from the plugin JavaScript to show or hide the launch screen.
- */
 - (void)showLaunchScreen:(BOOL)visible
+{
+    [self showSplashScreen:visible];
+}
+
+- (void)showSplashScreen:(BOOL)visible
 {
     CGFloat fadeSplashScreenDuration = [self.settings cordovaFloatSettingForKey:@"FadeSplashScreenDuration" defaultValue:250.f];
 

CordovaLib/CordovaLib.docc/CordovaLib.md

@@ -0,0 +1,69 @@
+# ``Cordova``
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+# 
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#  KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+-->
+
+Build your app using web technologies
+
+## Overview
+
+For more information about Apache Cordova, visit [https://cordova.apache.org](https://cordova.apache.org).
+
+## Topics
+
+### Using Cordova in your app
+
+- ``CDVAppDelegate``
+- ``CDVViewController``
+
+### Cordova plugins
+
+- ``CDVPlugin``
+- ``CDVPluginResult``
+- ``CDVCommandStatus``
+- ``CDVInvokedUrlCommand``
+- ``CDVCommandDelegate``
+
+### Web View plugins
+
+- ``CDVWebViewEngineProtocol``
+- ``CDVWebViewEngineConfigurationDelegate``
+
+### Utilities
+
+- ``CDVSettingsDictionary``
+- ``CDVCommandQueue``
+- ``CDVConfigParser``
+- ``CDVTimer``
+
+### Deprecated
+
+- ``IsAtLeastiOSVersion``
+- ``CDVScreenOrientationDelegate``
+- ``CDVCommandStatus_NO_RESULT`` <!-- Swift alias -->
+- ``CDVCommandStatus_OK`` <!-- Swift alias -->
+- ``CDVCommandStatus_CLASS_NOT_FOUND_EXCEPTION`` <!-- Swift alias -->
+- ``CDVCommandStatus_ILLEGAL_ACCESS_EXCEPTION`` <!-- Swift alias -->
+- ``CDVCommandStatus_INSTANTIATION_EXCEPTION`` <!-- Swift alias -->
+- ``CDVCommandStatus_MALFORMED_URL_EXCEPTION`` <!-- Swift alias -->
+- ``CDVCommandStatus_IO_EXCEPTION`` <!-- Swift alias -->
+- ``CDVCommandStatus_INVALID_ACTION`` <!-- Swift alias -->
+- ``CDVCommandStatus_JSON_EXCEPTION`` <!-- Swift alias -->
+- ``CDVCommandStatus_ERROR`` <!-- Swift alias -->

CordovaLib/CordovaLib.xcodeproj/project.pbxproj

@@ -81,6 +81,8 @@
 		7ED95D581AB9029B008C4574 /* NSDictionary+CordovaPreferences.m in Sources */ = {isa = PBXBuildFile; fileRef = 7ED95D321AB9029B008C4574 /* NSDictionary+CordovaPreferences.m */; };
 		7ED95D591AB9029B008C4574 /* NSMutableArray+QueueAdditions.h in Headers */ = {isa = PBXBuildFile; fileRef = 7ED95D331AB9029B008C4574 /* NSMutableArray+QueueAdditions.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		7ED95D5A1AB9029B008C4574 /* NSMutableArray+QueueAdditions.m in Sources */ = {isa = PBXBuildFile; fileRef = 7ED95D341AB9029B008C4574 /* NSMutableArray+QueueAdditions.m */; };
+		902B30742C6C5A7E00C6804C /* CordovaLib.docc in Sources */ = {isa = PBXBuildFile; fileRef = 902B30732C6C5A7E00C6804C /* CordovaLib.docc */; };
+		902B30752C6C5A7E00C6804C /* CordovaLib.docc in Sources */ = {isa = PBXBuildFile; fileRef = 902B30732C6C5A7E00C6804C /* CordovaLib.docc */; };
 		9036843D2C6EB06500A3338C /* CDVAllowList.h in Headers */ = {isa = PBXBuildFile; fileRef = 9036843B2C6EB06500A3338C /* CDVAllowList.h */; };
 		9036843E2C6EB06500A3338C /* CDVAllowList.m in Sources */ = {isa = PBXBuildFile; fileRef = 9036843C2C6EB06500A3338C /* CDVAllowList.m */; };
 		9036843F2C6EB06500A3338C /* CDVAllowList.m in Sources */ = {isa = PBXBuildFile; fileRef = 9036843C2C6EB06500A3338C /* CDVAllowList.m */; };
@@ -193,6 +195,7 @@
 		7ED95D331AB9029B008C4574 /* NSMutableArray+QueueAdditions.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "NSMutableArray+QueueAdditions.h"; sourceTree = "<group>"; };
 		7ED95D341AB9029B008C4574 /* NSMutableArray+QueueAdditions.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "NSMutableArray+QueueAdditions.m"; sourceTree = "<group>"; };
 		902D0BC12AEB64EB009C68E5 /* PrivacyInfo.xcprivacy */ = {isa = PBXFileReference; lastKnownFileType = text.xml; path = PrivacyInfo.xcprivacy; sourceTree = "<group>"; };
+		902B30732C6C5A7E00C6804C /* CordovaLib.docc */ = {isa = PBXFileReference; lastKnownFileType = folder.documentationcatalog; path = CordovaLib.docc; sourceTree = "<group>"; };
 		9036843B2C6EB06500A3338C /* CDVAllowList.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = CDVAllowList.h; sourceTree = "<group>"; };
 		9036843C2C6EB06500A3338C /* CDVAllowList.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = CDVAllowList.m; sourceTree = "<group>"; };
 		9047732D2C7A57E900373636 /* CDVURLSchemeHandler.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = CDVURLSchemeHandler.h; sourceTree = "<group>"; };
@@ -236,6 +239,7 @@
 		0867D691FE84028FC02AAC07 = {
 			isa = PBXGroup;
 			children = (
+				902B30732C6C5A7E00C6804C /* CordovaLib.docc */,
 				9064EF5E26FAB74200C9D65B /* include */,
 				7ED95D0E1AB9029B008C4574 /* Public */,
 				7ED95CF11AB9028C008C4574 /* Private */,
@@ -567,6 +571,7 @@
 				9052DE712150D040008E83D4 /* CDVAppDelegate.m in Sources */,
 				9052DE722150D040008E83D4 /* CDVCommandDelegateImpl.m in Sources */,
 				9052DE732150D040008E83D4 /* CDVCommandQueue.m in Sources */,
+				902B30742C6C5A7E00C6804C /* CordovaLib.docc in Sources */,
 				9052DE742150D040008E83D4 /* CDVConfigParser.m in Sources */,
 				9052DE752150D040008E83D4 /* CDVInvokedUrlCommand.m in Sources */,
 				9052DE762150D040008E83D4 /* CDVPlugin+Resources.m in Sources */,
@@ -598,6 +603,7 @@
 				7ED95D371AB9029B008C4574 /* CDVAppDelegate.m in Sources */,
 				7ED95D3C1AB9029B008C4574 /* CDVCommandDelegateImpl.m in Sources */,
 				7ED95D3E1AB9029B008C4574 /* CDVCommandQueue.m in Sources */,
+				902B30752C6C5A7E00C6804C /* CordovaLib.docc in Sources */,
 				7ED95D401AB9029B008C4574 /* CDVConfigParser.m in Sources */,
 				7ED95D421AB9029B008C4574 /* CDVInvokedUrlCommand.m in Sources */,
 				7ED95D441AB9029B008C4574 /* CDVPlugin+Resources.m in Sources */,
@@ -685,6 +691,7 @@
 				COPY_PHASE_STRIP = NO;
 				DEBUG_INFORMATION_FORMAT = dwarf;
 				DEFINES_MODULE = YES;
+				DOCC_EXTRACT_SWIFT_INFO_FOR_OBJC_SYMBOLS = YES;
 				ENABLE_MODULE_VERIFIER = YES;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				ENABLE_TESTABILITY = YES;
@@ -756,6 +763,7 @@
 				COPY_PHASE_STRIP = NO;
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
 				DEFINES_MODULE = YES;
+				DOCC_EXTRACT_SWIFT_INFO_FOR_OBJC_SYMBOLS = YES;
 				ENABLE_MODULE_VERIFIER = YES;
 				ENABLE_NS_ASSERTIONS = NO;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;

CordovaLib/include/Cordova/CDVCommandDelegate.h

@@ -29,24 +29,67 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol CDVCommandDelegate <NSObject>
 
 @optional
-@property (nonatomic, nullable, copy) NSURL *(^urlTransformer)(NSURL *) CDV_DEPRECATED(8, "Unused");
+
+@property (nonatomic, nullable, copy) NSURL *(^urlTransformer)(NSURL *) CDV_DEPRECATED(8, "");
 
 @required
+/**
+ The Cordova preferences for the web view.
+
+ This is a dictionary populated from the preference key/value pairs in the
+ Cordova XML configuration file.
+ */
 @property (nonatomic, readonly) CDVSettingsDictionary* settings;
 
-- (NSString*)pathForResource:(NSString*)resourcepath;
-- (id)getCommandInstance:(NSString*)pluginName;
-
-// Sends a plugin result to the JS. This is thread-safe.
-- (void)sendPluginResult:(CDVPluginResult*)result callbackId:(NSString*)callbackId;
-// Evaluates the given JS. This is thread-safe.
-- (void)evalJs:(NSString*)js;
-// Can be used to evaluate JS right away instead of scheduling it on the run-loop.
-// This is required for dispatch resign and pause events, but should not be used
-// without reason. Without the run-loop delay, alerts used in JS callbacks may result
-// in dead-lock. This method must be called from the UI thread.
-- (void)evalJs:(NSString*)js scheduledOnRunLoop:(BOOL)scheduledOnRunLoop;
-// Runs the given block on a background thread using a shared thread-pool.
+- (NSString *)pathForResource:(NSString *)resourcepath;
+
+/**
+ Returns the CDVPlugin instance of the given plugin name.
+
+ - Parameters:
+   - pluginName: The name of the plugin to return.
+ - Returns: The ``CDVPlugin`` instance, or `nil` if no plugin instance was
+   found with the given name.
+ */
+- (nullable CDVPlugin *)getCommandInstance:(NSString *)pluginName;
+
+/**
+ Sends a plugin result to the web view. This is thread-safe.
+
+ - Parameters:
+   - result: The plugin result to send to the web view.
+   - callbackId: The ID of the JavaScript callback to invoke.
+ */
+- (void)sendPluginResult:(CDVPluginResult *)result callbackId:(NSString *)callbackId;
+
+/**
+ Evaluates the given JavaScript string in the web view. This is thread-safe.
+
+ - Parameters:
+   - js: The string of JavaScript code to run.
+ */
+- (void)evalJs:(NSString *)js;
+
+/**
+ Evaluates the given JavaScript string right away instead of scheduling it on
+ the run-loop.
+
+ This is required for dispatching `resign` and `pause` events, but should not
+ be used without reason. Without the run-loop delay, alerts used in JS callbacks
+ may result in dead-lock. This method must be called from the UI thread.
+
+ - Parameters:
+   - js: The string of JavaScript code to run.
+   - scheduledOnRunLoop: Whether to schedule the code to run on the run-loop.
+ */
+- (void)evalJs:(NSString *)js scheduledOnRunLoop:(BOOL)scheduledOnRunLoop;
+
+/**
+ Runs the given block on a background thread using a shared thread-pool.
+
+ - Parameters:
+   - block: The block to be run.
+ */
 - (void)runInBackground:(void (^)(void))block;
 
 @end

CordovaLib/include/Cordova/CDVPlugin.h

@@ -21,7 +21,6 @@
 #import <UIKit/UIKit.h>
 #import <Cordova/CDVAvailabilityDeprecated.h>
 #import <Cordova/CDVPluginResult.h>
-#import <Cordova/NSMutableArray+QueueAdditions.h>
 #import <Cordova/CDVCommandDelegate.h>
 #import <Cordova/CDVSettingsDictionary.h>
 #import <Cordova/CDVViewController.h>

CordovaLib/include/Cordova/CDVPluginResult.h

@@ -20,16 +20,42 @@
 #import <Foundation/Foundation.h>
 #import <Cordova/CDVAvailability.h>
 
+/**
+ An enumeration that describes the result of handling a plugin command.
+
+ ## See Also
+
+ - ``CDVPluginResult``
+ */
 typedef NS_ENUM(NSUInteger, CDVCommandStatus) {
+    /** Status code indicating no command result. */
     CDVCommandStatus_NO_RESULT NS_SWIFT_NAME(noResult) = 0,
+
+    /** Status code indicating successful handling of the command. */
     CDVCommandStatus_OK NS_SWIFT_NAME(ok),
+
+    /** Status code indicating the command's plugin class could not be found. */
     CDVCommandStatus_CLASS_NOT_FOUND_EXCEPTION NS_SWIFT_NAME(classNotFoundException),
+
+    /** Status code indicating there was an illegal access exception while handling the command. */
     CDVCommandStatus_ILLEGAL_ACCESS_EXCEPTION NS_SWIFT_NAME(illegalAccessException),
+
+    /** Status code indicating the command's plugin class could not be instantiated. */
     CDVCommandStatus_INSTANTIATION_EXCEPTION NS_SWIFT_NAME(instantiationException),
+
+    /** Status code indicating the command included a malformed URL. */
     CDVCommandStatus_MALFORMED_URL_EXCEPTION NS_SWIFT_NAME(malformedUrlException),
+
+    /** Status code indicating there was an I/O exception while handling the command. */
     CDVCommandStatus_IO_EXCEPTION NS_SWIFT_NAME(ioException),
+
+    /** Status code indicating the command's action was not valid. */
     CDVCommandStatus_INVALID_ACTION NS_SWIFT_NAME(invalidAction),
+
+    /** Status code indicating the command's JSON data was invalid. */
     CDVCommandStatus_JSON_EXCEPTION NS_SWIFT_NAME(jsonException),
+
+    /** Status code indicating there was an error handling the command. */
     CDVCommandStatus_ERROR NS_SWIFT_NAME(error)
 };
 
@@ -59,11 +85,9 @@ NS_ASSUME_NONNULL_BEGIN
 @interface CDVPluginResult : NSObject {}
 
 @property (nonatomic, strong, readonly) NSNumber *status;
-@property (nonatomic, strong, readonly) id message;
-@property (nonatomic, strong)           NSNumber *keepCallback;
-// This property can be used to scope the lifetime of another object. For example,
-// Use it to store the associated NSData when `message` is created using initWithBytesNoCopy.
-@property (nonatomic, strong) id associatedObject;
+@property (nonatomic, nullable, strong, readonly) id message;
+@property (nonatomic, strong) NSNumber *keepCallback;
+@property (nonatomic, strong) id associatedObject CDV_DEPRECATED(8, "");
 
 - (instancetype)init;
 + (instancetype)resultWithStatus:(CDVCommandStatus)statusOrdinal;
@@ -79,8 +103,8 @@ NS_ASSUME_NONNULL_BEGIN
 + (instancetype)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAsMultipart:(NSArray *)theMessages;
 + (instancetype)resultWithStatus:(CDVCommandStatus)statusOrdinal messageToErrorObject:(int)errorCode;
 
-+ (void)setVerbose:(BOOL)verbose;
-+ (BOOL)isVerbose;
++ (void)setVerbose:(BOOL)verbose CDV_DEPRECATED(8, "");
++ (BOOL)isVerbose CDV_DEPRECATED(8, "");
 
 - (void)setKeepCallbackAsBool:(BOOL)bKeepCallback;
 

CordovaLib/include/Cordova/CDVScreenOrientationDelegate.h

@@ -20,7 +20,7 @@
 #import <Foundation/Foundation.h>
 #import <Cordova/CDVAvailabilityDeprecated.h>
 
-CDV_DEPRECATED(8, "Unused")
+CDV_DEPRECATED(8, "")
 @protocol CDVScreenOrientationDelegate <NSObject>
 
 - (UIInterfaceOrientationMask)supportedInterfaceOrientations;