Merge pull request #34 from PureSwift/feature/docs

Add documentation and availability annotations for `AndroidOS`

Author: colemancda

Sources/AndroidInput/Syscalls.swift

@@ -34,12 +34,23 @@ public extension AndroidAPI {
 
 internal extension AndroidAPI {
 
+    /**
+     Returns the targetSdkVersion of the caller, or __ANDROID_API_FUTURE__ if there is no known target SDK version (for code not running in the context of an app).
+
+     The returned value is the same as the AndroidManifest.xml targetSdkVersion. This is mostly useful for the OS to decide what behavior an app is expecting. See also android_get_device_api_level().
+
+     Available since API level 24. Returns the API level of the device we're actually running on, or -1 on failure.
+
+     The returned value is the same as the Java Build.VERSION.SDK_INT. This is mostly useful for an app to work out what version of the OS it's running on. See also android_get_application_target_sdk_version().
+
+     Available since API level 29.
+     */
     static func deviceAPILevel() throws -> Int32 {
-        #if os(Android) && canImport(CAndroidNDK)
-        try ndkValue().get()
-        #else
-        try jniValue()
-        #endif
+        if #available(Android 24, *) {
+            try ndkValue().get()
+        } else {
+            try jniValue()
+        }
     }
 
     /// `Build.VERSION.SDK_INT`

Sources/AndroidOS/AndroidAPI.swift

@@ -2,6 +2,10 @@
 import SwiftJava
 import CSwiftJavaJNI
 
+/// Thrown when a `Parcelable` encounters an error during marshalling or unmarshalling,
+/// such as when a class cannot be found or data is malformed.
+///
+/// See also: [android.os.BadParcelableException](https://developer.android.com/reference/android/os/BadParcelableException)
 @JavaClass("android.os.BadParcelableException")
 open class BadParcelableException: RuntimeException {
   @JavaMethod

Sources/AndroidOS/BadParcelableException.swift

@@ -2,104 +2,158 @@
 import SwiftJava
 import CSwiftJavaJNI
 
+/// A mapping from String keys to values of various types. The only types currently supported
+/// are: Boolean, Int, Long, Double, String, and arrays of each of these types.
+///
+/// This is the base class for `Bundle` and `PersistableBundle`.
+///
+/// See also: [android.os.BaseBundle](https://developer.android.com/reference/android/os/BaseBundle)
+@available(Android 21, *)
 @JavaClass("android.os.BaseBundle")
 open class BaseBundle: JavaObject {
+  /// Inserts a String value into the mapping, replacing any existing value for the given key.
   @JavaMethod
   open func putString(_ arg0: String, _ arg1: String)
 
+  /// Inserts a boolean array value into the mapping.
   @JavaMethod
   open func putBooleanArray(_ arg0: String, _ arg1: [Bool])
 
+  /// Inserts an int array value into the mapping.
   @JavaMethod
   open func putIntArray(_ arg0: String, _ arg1: [Int32])
 
+  /// Inserts a long array value into the mapping.
   @JavaMethod
   open func putLongArray(_ arg0: String, _ arg1: [Int64])
 
+  /// Inserts a double array value into the mapping.
   @JavaMethod
   open func putDoubleArray(_ arg0: String, _ arg1: [Double])
 
+  /// Inserts a String array value into the mapping.
   @JavaMethod
   open func putStringArray(_ arg0: String, _ arg1: [String])
 
+  /// Returns the value associated with the given key, or nil if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getBooleanArray(_ arg0: String) -> [Bool]
 
+  /// Returns the value associated with the given key, or nil if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getIntArray(_ arg0: String) -> [Int32]
 
+  /// Returns the value associated with the given key, or nil if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getLongArray(_ arg0: String) -> [Int64]
 
+  /// Returns the value associated with the given key, or nil if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getDoubleArray(_ arg0: String) -> [Double]
 
+  /// Removes any entry with the given key from the mapping.
   @JavaMethod
   open func remove(_ arg0: String)
 
+  /// Returns the number of mappings contained in this Bundle.
   @JavaMethod
   open func size() -> Int32
 
+  /// Returns the entry with the given key as an object.
   @JavaMethod
   open func get(_ arg0: String) -> JavaObject!
 
+  /// Returns the value associated with the given key, or `false` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getBoolean(_ arg0: String) -> Bool
 
+  /// Returns the value associated with the given key, or `arg1` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getBoolean(_ arg0: String, _ arg1: Bool) -> Bool
 
+  /// Inserts a Boolean value into the mapping.
   @JavaMethod
   open func putBoolean(_ arg0: String, _ arg1: Bool)
 
+  /// Returns the value associated with the given key, or `0` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getInt(_ arg0: String) -> Int32
 
+  /// Returns the value associated with the given key, or `arg1` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getInt(_ arg0: String, _ arg1: Int32) -> Int32
 
+  /// Inserts an int value into the mapping.
   @JavaMethod
   open func putInt(_ arg0: String, _ arg1: Int32)
 
+  /// Returns the value associated with the given key, or `arg1` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getLong(_ arg0: String, _ arg1: Int64) -> Int64
 
+  /// Returns the value associated with the given key, or `0L` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getLong(_ arg0: String) -> Int64
 
+  /// Inserts a long value into the mapping.
   @JavaMethod
   open func putLong(_ arg0: String, _ arg1: Int64)
 
+  /// Returns the value associated with the given key, or `arg1` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getDouble(_ arg0: String, _ arg1: Double) -> Double
 
+  /// Returns the value associated with the given key, or `0.0` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getDouble(_ arg0: String) -> Double
 
+  /// Inserts a double value into the mapping.
   @JavaMethod
   open func putDouble(_ arg0: String, _ arg1: Double)
 
+  /// Removes all elements from the mapping.
   @JavaMethod
   open func clear()
 
+  /// Returns true if the mapping is empty, false otherwise.
   @JavaMethod
   open func isEmpty() -> Bool
 
+  /// Inserts all mappings from the given `PersistableBundle` into this Bundle.
   @JavaMethod
   open func putAll(_ arg0: PersistableBundle?)
 
+  /// Returns a Set containing the Strings used as keys in this Bundle.
   @JavaMethod
   open func keySet() -> JavaSet<JavaString>!
 
+  /// Returns true if the given key is contained in the mapping.
   @JavaMethod
   open func containsKey(_ arg0: String) -> Bool
 
+  /// Returns the value associated with the given key, or nil if no mapping exists.
   @JavaMethod
   open func getStringArray(_ arg0: String) -> [String]
 
+  /// Returns the value associated with the given key, or nil if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getString(_ arg0: String) -> String
 
+  /// Returns the value associated with the given key, or `arg1` if no mapping of the desired type
+  /// exists for the given key.
   @JavaMethod
   open func getString(_ arg0: String, _ arg1: String) -> String
 }

Sources/AndroidOS/BaseBundle.swift

@@ -2,17 +2,27 @@
 import SwiftJava
 import CSwiftJavaJNI
 
+/// Provides information about battery state and charging status.
+///
+/// Obtain an instance via `Context.getSystemService(Context.BATTERY_SERVICE)`.
+///
+/// See [android.os.BatteryManager](https://developer.android.com/reference/android/os/BatteryManager)
+@available(Android 21, *)
 @JavaClass("android.os.BatteryManager")
 open class BatteryManager: JavaObject {
+  /// Returns whether the device is currently charging.
   @JavaMethod
   open func isCharging() -> Bool
 
+  /// Returns an estimate of how long until the battery is fully charged, in milliseconds, or `-1` if unknown.
   @JavaMethod
   open func computeChargeTimeRemaining() -> Int64
 
+  /// Returns the value of the given integer battery property (e.g., `BATTERY_PROPERTY_CAPACITY`).
   @JavaMethod
   open func getIntProperty(_ arg0: Int32) -> Int32
 
+  /// Returns the value of the given long battery property (e.g., `BATTERY_PROPERTY_ENERGY_COUNTER`).
   @JavaMethod
   open func getLongProperty(_ arg0: Int32) -> Int64
 }