[enumification-helpers] API O method enumification.

Author: atsushieno

Documentation/HowToAddNewApiLevel.md

@@ -0,0 +1,32 @@
+
+# How to deal with new API Level
+
+## This documentation is incomplete
+
+In Xamarin ages, we used to have (more complete) API upgrade guide internally. But since then we switched to new xamarin-android repository which entirely changed the build system from Makefile to MSBuild solution, as well as the managed API for manipulating Android SDK, the old documentation almost does not make sense anymore. Even though I am writing this documentation, I don't know everything required (nor those who changed the build system didn't care about API upgrades).
+
+Hence, this documentation is written from the ground,  exploring everything around.
+
+And since the build system has changed between the first preview of Android O and the latest Android O preview (3), and it is quite possible that the build system changes over and over again, it might still not make much sense in the future.
+
+## Steps
+
+Anyhow, this commit would tell you what needs to be changed when the new API preview arrives (and that becomes stable): https://github.com/xamarin/xamarin-android/pull/642
+
+1) Add/update new download to build-tools/android-toolchain.
+The new API archive should be found on the web repository description
+that Google Android SDK Manager uses (which can be now shown as part
+of SDK Manager options in Android Studio).
+
+As of Android O ages, it could be found at https://dl-ssl.google.com/android/repository/repository2-1.xml . It used to be different repository description URL, and it will be different URL in the future.
+
+2) Create and add api-O.xml.in under src/Mono.Android/Profile directory.
+It can be done from within `build-tools/api-xml-adjuster` directory. See `README.md` in that directory for details. You will have to make changes to Makefile in that directory to generate it. Also note that it often happens that Google does not ship documentation archive (!) and in such case we will have to scrape DroidDoc from the web and create our own docs archive.
+
+3) Review new API (or review the changes in case of API updates).
+
+Some of the changes are caused by API removal. Usually they come with
+"deprecated" state in the previous API Level first, but that's not always true.
+
+4) enumification: See `build-tools/enumification-helpers/README`.
+

build-tools/enumification-helpers/.gitignore

@@ -1,5 +1,6 @@
 map.ext.csv
 const-list-*.xml
+remaining-int-methods.txt
 *.exe
 *.mdb
 *.pdb

build-tools/enumification-helpers/README

@@ -231,6 +231,15 @@ The results are to be saved as "map.ext.csv" and "methodmap.ext.csv" that are to
 		  convert to enums" methods, or blacklist-field.txt for fields.
 		- in general those notes do not describe *everything*. git diff
 		  would tell what is new and what should be taken care this time.
+	  - Here is how I worked on it at API Level 26 to add new lines to methodmap.ext.csv:
+		- Read git diff on remaining-int-consts.txt to iterate all the new enum types.
+		- For each new enum type that (typically) has prefix P_ in type T, I run `grep -R P_ | grep T | grep "\w*.html:"` in the local reference docs, to see which documentation HTML mention that const (I ran the command on GNOME terminal, so I got the final grep matches with color highlights).
+		- And for each HTML doc, look up that const and add records to methodmap.ext.csv.
+		- I usually bring in mistakes. When there are wrong const mappings, they will result in binding generator warnings for unmatched XPath selectors that you can find them by looking up enummetadata.
+		- For method mappings, mistakes can be twofolds:
+		  - For the wrong matching, you'll see them as binding generator warnings for unmatched XPath selectors just like const mappings.
+		  - For the wrong replacement enum type, that's NOT going to be unmatched XPath. Instead it will result in a reference to missing type warning that can be still found as a generator warning (but harder to find).
+		  - It is often hard to identify why the mappings are regarded as invalid; sometimes Google API reference tells you lies(!) that there are some methods that actually don't exist(!). You'd like to check `obj/Debug/android-*/api.xml`, `obj/Debug/android-*/api.xml.fixed` (XML after applying metadata fixup) or `Profiles/api-*.xml.in` (for "raw" API data before `api-merge` step).
 	  - At some stage, go to src/Mono.Android and append
 	    methodmap.ext.csv contents to methodmap.csv and run
 	    "make API_LEVELS=[latest] clean all" to get enumified dll.

build-tools/enumification-helpers/enum-conversion-mappings.xml

@@ -56,10 +56,10 @@
   <map package="android.app" class="DownloadManager.Request" fields="" prefix="VISIBILITY_" enum-name="DownloadVisibility" />
   <map package="android.app" class="FragmentManager" fields="" prefix="POP_BACK_STACK_" enum-name="PopBackStackFlags" extra-default="None" />
   <map package="android.app" class="FragmentTransaction" fields="" prefix="TRANSIT_" enum-name="FragmentTransit" is-transient="false" />
-  <map package="android.app" class="Notification" fields="" prefix="BADGE_ICON_" enum-name="NotificationBadgeIcon" is-transient="false" api-since="26" />
+  <map package="android.app" class="Notification" fields="" prefix="BADGE_ICON_" enum-name="NotificationBadgeIconType" is-transient="false" api-since="26" />
   <map package="android.app" class="Notification" fields="" prefix="FLAG_" enum-name="NotificationFlags" is-transient="false" />
   <map package="android.app" class="Notification" fields="" prefix="DEFAULT_" enum-name="NotificationDefaults" is-transient="false" />
-  <map package="android.app" class="Notification" fields="" prefix="GROUP_ALERT_" enum-name="NotificationGroupAlert" is-transient="false" api-since="26" />
+  <map package="android.app" class="Notification" fields="" prefix="GROUP_ALERT_" enum-name="NotificationGroupAlertBehavior" is-transient="false" api-since="26" />
   <map package="android.app" class="Notification" fields="" prefix="VISIBILITY_" enum-name="NotificationVisibility" is-transient="false" api-level="20" />
   <map package="android.app" class="Notification.WearableExtender" fields="" prefix="SIZE_" enum-name="WearableSizePreset" is-transient="false" api-level="20" />
   <map package='android.app' class='PendingIntent' prefix='FLAG_' enum-name='PendingIntentFlags' is-transient='false' />
@@ -97,6 +97,8 @@
   <map package="android.bluetooth" class="BluetoothDevice" fields="" prefix="BOND_" enum-name="Bond" is-transient="false" />
   <map package="android.bluetooth" class="BluetoothDevice" fields="PHY_LE_*" prefix="PHY_" enum-name="BluetoothPhy" is-transient="false" api-level="26" />
   <map package="android.bluetooth" class="BluetoothDevice" prefix="PHY_OPTION_" enum-name="BluetoothPhyOption" is-transient="false" api-level="26" />
+  <!-- used by ScanResult#getSecondaryPhy() -->
+  <map package="android.bluetooth.le" class="ScanResult" fields="PHY_UNUSED" prefix="PHY_" enum-name="BluetoothPhy" is-transient="false" api-level="26" />
   <map package="android.bluetooth" class="BluetoothGatt" fields="" prefix="GATT_" enum-name="GattStatus" api-level="18" />
   <map package="android.bluetooth" class="BluetoothGatt" fields="" prefix="CONNECTION_PRIORITY_" enum-name="GattConnectionPriority" api-level="21" />
   <map package="android.bluetooth" class="BluetoothGattCharacteristic" fields="" prefix="FORMAT_" enum-name="GattFormat" api-level="18" />
@@ -118,10 +120,9 @@
   <map package="android.bluetooth.le" class="AdvertiseSettings" fields="" prefix="ADVERTISE_TX_" enum-name="AdvertiseTx" is-transient="false" api-level="21" />
   <map package="android.bluetooth.le" class="AdvertiseSettings" fields="" prefix="ADVERTISE_TYPE_" enum-name="AdvertiseType" is-transient="false" api-level="21" />
   <map package="android.bluetooth.le" class="AdvertisingSetCallback" fields="" prefix="ADVERTISE_" enum-name="AdvertiseResult" is-transient="false" api-level="26" />
-  <map package="android.bluetooth.le" class="AdvertisingSetParameters" fields="" prefix="INTERVAL_" enum-name="AdvertiseInterval" is-transient="false" api-level="26" />
   <map package="android.bluetooth.le" class="AdvertisingSetParameters" fields="" prefix="TX_POWER_" enum-name="AdvertiseTxPower" is-transient="false" api-level="26" />
   <map package="android.bluetooth.le" class="ScanCallback" fields="" prefix="SCAN_FAILED_" enum-name="ScanFailure" is-transient="false" api-level="21" />
-  <map package="android.bluetooth.le" class="ScanResult" fields="*" prefix="" enum-name="ScanResultCode" is-transient="false" api-level="26" />
+  <map package="android.bluetooth.le" class="ScanResult" prefix="DATA_" enum-name="DataStatus" is-transient="false" api-level="26" />
   <map package="android.bluetooth.le" class="ScanSettings" fields="" prefix="SCAN_MODE_" enum-name="ScanMode" is-transient="false" api-level="21" />
   <map package="android.bluetooth.le" class="ScanSettings" fields="" prefix="CALLBACK_TYPE_" enum-name="ScanCallbackType" is-transient="false" api-level="21" />
   <map package="android.bluetooth.le" class="ScanSettings" fields="" prefix="PHY_LE_" enum-name="ScanSettingsPhy" is-transient="false" api-level="26" />
@@ -198,11 +199,12 @@
   <map package='android.hardware' class='Camera$CameraInfo' fields='' prefix='CAMERA_FACING_' enum-name="CameraFacing" />
   <map package='android.hardware' class='Camera$Parameters' fields='' prefix='FOCUS_DISTANCE_' enum-name="FocusDistance" />
   <map package='android.hardware' class='Camera$Parameters' fields='' prefix='PREVIEW_' enum-name="Preview" />
-  <map package='android.hardware' class='HardwareBuffer' fields='*' enum-name="HardwareBufferFlags" is-transient="false" api-level="26" />
+  <map package='android.hardware' class='HardwareBuffer' fields='RGB.* BLOB' enum-name="HardwareBufferFormat" is-transient="false" api-level="26" />
+  <map package='android.hardware' class='HardwareBuffer' prefix='USAGE_' enum-name="HardwareBufferUsage" is-transient="false" api-level="26" />
   <map package='android.hardware' class='Sensor' prefix='REPORTING_MODE_' enum-name="ReportingMode" is-transient="false" api-level="21" />
   <map package='android.hardware' class='Sensor' fields='' prefix='TYPE_' enum-name="SensorType" is-transient="false" />
   <map package='android.hardware' class='SensorDirectChannel' prefix='RATE_' enum-name="SensorDirectRateLevel" is-transient="false" api-level="26" />
-  <map package='android.hardware' class='SensorDirectChannel' prefix='TYPE_' enum-name="SensorDirectType" is-transient="false" api-level="26" />
+  <map package='android.hardware' class='SensorDirectChannel' prefix='TYPE_' enum-name="SensorDirectChannelType" is-transient="false" api-level="26" />
   <map package='android.hardware.camera2' class='CameraAccessException' fields='' prefix='CAMERA_' enum-name="CameraAccessErrorType" is-transient="false" api-level="21" />
   <map package='android.hardware.camera2' class='CameraDevice.StateCallback' fields='' prefix='ERROR_' enum-name="CameraError" is-transient="false" api-level="21" />
   <map package='android.hardware.camera2' class='CameraDevice' fields='' prefix='TEMPLATE_' enum-name="CameraTemplate" is-transient="false" api-level="21" />
@@ -1000,7 +1002,6 @@
   <map package='android.icu.util' class='Calendar' fields='AM_PM DATE DAY_OF_MONTH DAY_OF_WEEK DAY_OF_WEEK_IN_MONTH DAY_OF_YEAR DOW_LOCAL DST_OFFSET ERA EXTENDED_YEAR HOUR HOUR_OF_DAY JULIAN_DAY MILLISECOND MILLISECONDS_IN_DAY MINUTE MONTH SECOND WEEK_OF_MONTH WEEK_OF_YEAR YEAR YEAR_WOY ZONE_OFFSET' prefix='' enum-name="CalendarField" />
   <map package="android.icu.util" class="Calendar" fields="" prefix="WALLTIME_" enum-name="WalltimeOptions" api-level="24" />
   <map package="android.icu.util" class="Currency" fields="" suffix="_NAME" enum-name="CurrencyNameStyle" api-level="24" />
-  <map package="android.icu.util" class="EthiopicCalendar" fields="*" prefix="" enum-name="EthiopicMonth" api-level="26" />
   <map package="android.icu.util" class="TimeZone" fields="GENERIC_LOCATION LONG* SHORT*" enum-name="TimeZoneNameStyle" api-level="24" />
   <map package="android.icu.util" class="TimeZone" prefix="TIMEZONE_" enum-name="TimeZoneType" api-level="26" />
   <map package="android.icu.util" class="UniversalTimeScale" fields=".*_TIME MAX_SCALE" enum-name="UniversalTimeScaleType" api-level="26" />