[generator] Obsolete&SupportedOSPlatform attributes on enum members (#1066)

Fixes: #1037
Adds support for emitting `[Obsolete]`, `[ObsoletedOSPlatform]`, and
`[SupportedOSPlatform]` custom attributes on enum members.
~~ [SupportedOSPlatform] ~~
The data for `[SupportedOSPlatform]` comes from the values provided
in the enum-mapping file (b00e644), e.g.
[`xamarin-android/src/Mono.Android/map.csv`][0]:
// src/Mono.Android/map.csv
E,29,android/media/MediaRecorder$AudioEncoder.OPUS,7,Android.Media.AudioEncoder,Opus,keep,
The `29` is the API in which we added the enum, which becomes
`[SupportedOSPlatform("android-29.0")]`.
~~ [Obsolete] and [ObsoletedOSPlatform] ~~
The data for the "obsolete" attributes comes from the `deprecated`
and `deprecated-since` attributes on the original field in the
`api.xml`, if it can be found. For example, given:
<class name="AccessibilityServiceInfo" jni-signature="Landroid/accessibilityservice/AccessibilityServiceInfo;" …>
<field
deprecated="deprecated"
final="true"
name="CAPABILITY_CAN_REQUEST_ENHANCED_WEB_ACCESSIBILITY"
jni-signature="I"
static="true"
transient="false"
type="int"
type-generic-aware="int"
value="4"
visibility="public"
volatile="false"
deprecated-since="26"
/>
</class>
in combination with these `map.csv` (b00e644) entries:
A,0,,0,Android.AccessibilityServices.AccessibilityServiceCapabilities,None,remove,
E,18,android/accessibilityservice/AccessibilityServiceInfo.CAPABILITY_CAN_REQUEST_ENHANCED_WEB_ACCESSIBILITY,4,Android.AccessibilityServices.AccessibilityServiceCapabilities,CanRequestEnhancedWebAccessibility,remove,
results in:
/* partial */ enum AccessibilityServiceCapabilities {
// When using classic obsolete attributes:
[global::System.Obsolete("deprecated")]
// When using new obsolete attributes:
[global::System.Runtime.Versioning.ObsoletedOSPlatform("android31.0")]
CanRequestEnhancedWebAccessibility = 4,
}
One wrinkle is we may have obsoleted the field because we want the
user to use the enum instead:
<field
deprecated='This constant will be removed in the future version. Use Android.App.RecentTaskFlags enum directly instead of this field.'
name='RECENT_IGNORE_UNAVAILABLE'
…
/>
We need to detect this message and not obsolete the enum in this case.
[0]: https://github.com/xamarin/xamarin-android/blob/17213ea184e23a9020451b265fec459558278489/src/Mono.Android/map.csv

Author: jpobst

tests/generator-Tests/Unit-Tests/EnumGeneratorTests.cs

@@ -1,24 +1,26 @@
 usingSystem;
 usingSystem.Collections.Generic;
 usingSystem.IO;
+usingSystem.Linq;
 usingSystem.Reflection;
 usingSystem.Text;
 usingJava.Interop.Tools.Generator.Enumification;
 usingMonoDroid.Generation;
 usingNUnit.Framework;
 usingNUnit.Framework.Internal;
+usingXamarin.Android.Binder;
 
 namespacegeneratortests
 {
 [TestFixture]
-classEnumGeneratorTests
+classEnumGeneratorTests:CodeGeneratorTestBase
 {
-protectedEnumGeneratorgenerator;
-protectedStringBuilderbuilder;
-protectedStringWriterwriter;
+protectednewEnumGeneratorgenerator;
+
+protectedoverrideCodeGenerationTargetTarget=>CodeGenerationTarget.XAJavaInterop1;
 
 [SetUp]
-publicvoidSetUp()
+publicnewvoidSetUp()
 {
 builder=newStringBuilder();
 writer=newStringWriter(builder);
@@ -60,7 +62,78 @@ public void WriteEnumWithGens ()
 Assert.AreEqual(GetExpected(nameof(WriteEnumWithGens)),writer.ToString().NormalizeLineEndings());
 }
 
-protectedstringGetExpected(stringtestName)
+[Test]
+publicvoidObsoletedOSPlatformAttributeSupport()
+{
+varxml=@"<api>
+ <package name='java.lang' jni-name='java/lang'>
+ <class abstract='false' deprecated='not deprecated' final='false' name='Object' static='false' visibility='public' jni-signature='Ljava/lang/Object;' />
+ </package>
+ <package name='android.app' jni-name='android/app'>
+ <class abstract='false' deprecated='not deprecated' extends='java.lang.Object' extends-generic-aware='java.lang.Object' jni-extends='Ljava/lang/Object;' final='false' name='ActivityManager' static='false' visibility='public' jni-signature='Landroid/app/ActivityManager;'>
+ <field deprecated='deprecated' final='true' name='RECENT_IGNORE_UNAVAILABLE' jni-signature='Ljava/lang/String;' static='true' transient='false' type='java.lang.String' type-generic-aware='java.lang.String' value='&quot;android.permission.BIND_CHOOSER_TARGET_SERVICE&quot;' visibility='public' volatile='false' deprecated-since='31' api-since='30' />
+ </class>
+ </package>
+ </api>";
+
+options.UseObsoletedOSPlatformAttributes=true;
+
+varenu=CreateEnum();
+vargens=ParseApiDefinition(xml);
+
+generator.WriteEnumeration(options,enu,gens.ToArray());
+
+// Ensure [ObsoletedOSPlatform] and [SupportedOSPlatform] are written
+Assert.True(writer.ToString().NormalizeLineEndings().Contains("[global::System.Runtime.Versioning.SupportedOSPlatformAttribute(\"android30.0\")][global::System.Runtime.Versioning.ObsoletedOSPlatform(\"android31.0\")]WithExcluded=1"),writer.ToString());
+}
+
+[Test]
+publicvoidObsoleteAttributeSupport()
+{
+varxml=@"<api>
+ <package name='java.lang' jni-name='java/lang'>
+ <class abstract='false' deprecated='not deprecated' final='false' name='Object' static='false' visibility='public' jni-signature='Ljava/lang/Object;' />
+ </package>
+ <package name='android.app' jni-name='android/app'>
+ <class abstract='false' deprecated='not deprecated' extends='java.lang.Object' extends-generic-aware='java.lang.Object' jni-extends='Ljava/lang/Object;' final='false' name='ActivityManager' static='false' visibility='public' jni-signature='Landroid/app/ActivityManager;'>
+ <field deprecated='deprecated' final='true' name='RECENT_IGNORE_UNAVAILABLE' jni-signature='Ljava/lang/String;' static='true' transient='false' type='java.lang.String' type-generic-aware='java.lang.String' value='&quot;android.permission.BIND_CHOOSER_TARGET_SERVICE&quot;' visibility='public' volatile='false' deprecated-since='31' api-since='30' />
+ </class>
+ </package>
+ </api>";
+
+varenu=CreateEnum();
+vargens=ParseApiDefinition(xml);
+
+generator.WriteEnumeration(options,enu,gens.ToArray());
+
+// Ensure [Obsolete] is written
+Assert.True(writer.ToString().NormalizeLineEndings().Contains("[global::System.Obsolete(@\"deprecated\")]WithExcluded=1"),writer.ToString());
+}
+
+[Test]
+publicvoidObsoleteFieldButNotEnumAttributeSupport()
+{
+varxml=@"<api>
+ <package name='java.lang' jni-name='java/lang'>
+ <class abstract='false' deprecated='not deprecated' final='false' name='Object' static='false' visibility='public' jni-signature='Ljava/lang/Object;' />
+ </package>
+ <package name='android.app' jni-name='android/app'>
+ <class abstract='false' deprecated='not deprecated' extends='java.lang.Object' extends-generic-aware='java.lang.Object' jni-extends='Ljava/lang/Object;' final='false' name='ActivityManager' static='false' visibility='public' jni-signature='Landroid/app/ActivityManager;'>
+ <field deprecated='This constant will be removed in the future version. Use Android.App.RecentTaskFlags enum directly instead of this field.' final='true' name='RECENT_IGNORE_UNAVAILABLE' jni-signature='Ljava/lang/String;' static='true' transient='false' type='java.lang.String' type-generic-aware='java.lang.String' value='&quot;android.permission.BIND_CHOOSER_TARGET_SERVICE&quot;' visibility='public' volatile='false' deprecated-since='31' api-since='30' />
+ </class>
+ </package>
+ </api>";
+
+varenu=CreateEnum();
+vargens=ParseApiDefinition(xml);
+
+generator.WriteEnumeration(options,enu,gens.ToArray());
+
+// [Obsolete] should not be written because the value isn't deprecated, just the _field_ is deprecated because we want people to use the enum instead
+Assert.False(writer.ToString().NormalizeLineEndings().Contains("[global::System.Obsolete(@\"deprecated\")]WithExcluded=1"),writer.ToString());
+}
+
+protectednewstringGetExpected(stringtestName)
 {
 varroot=Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
 
@@ -71,7 +144,7 @@ protected string GetExpected (string testName)
 {
 varenu=newEnumMappings.EnumDescription{
 Members=newList<ConstantEntry>{
-newConstantEntry{EnumMember="WithExcluded",Value="1",JavaSignature="android/app/ActivityManager.RECENT_IGNORE_UNAVAILABLE"},
+newConstantEntry{EnumMember="WithExcluded",Value="1",JavaSignature="android/app/ActivityManager.RECENT_IGNORE_UNAVAILABLE",ApiLevel=30},
 newConstantEntry{EnumMember="IgnoreUnavailable",Value="2",JavaSignature="android/app/ActivityManager.RECENT_WITH_EXCLUDED"}
 },
 BitField=false,

tools/generator/Java.Interop.Tools.Generator.CodeGeneration/EnumGenerator.cs

@@ -50,36 +50,43 @@ EnumWriter CreateWriter (CodeGenerationOptions opt, KeyValuePair<string, EnumDes
 Value=member.Value.Trim(),
 };
 
+// Try to find the original field in our model
 varmanagedMember=FindManagedMember(enu.Value,member,gens);
+varmanagedMemberName=managedMember!=null?$"{managedMember.Value.Cls.FullName}.{managedMember.Value.Field.Name}":null;
 
 if(opt.CodeGenerationTarget!=CodeGenerationTarget.JavaInterop1)
-m.Attributes.Add(newIntDefinitionAttr(managedMember,StripExtraInterfaceSpec(member.JavaSignature)));
+m.Attributes.Add(newIntDefinitionAttr(managedMemberName,StripExtraInterfaceSpec(member.JavaSignature)));
+
+SourceWriterExtensions.AddSupportedOSPlatform(m.Attributes,member.ApiLevel,opt);
+
+// Some of our source fields may have been marked with:
+// "This constant will be removed in the future version. Use XXX enum directly instead of this field."
+// We don't want this message to propogate to the enum.
+if(managedMember!=null&&managedMember.Value.Field?.DeprecatedComment?.Contains("enum directly instead of this field")==false)
+SourceWriterExtensions.AddObsolete(m.Attributes,managedMember.Value.Field.DeprecatedComment,opt,deprecatedSince:managedMember.Value.Field.DeprecatedSince);
 
 enoom.Members.Add(m);
 }
 
 returnenoom;
 }
 
-stringFindManagedMember(EnumDescriptiondesc,ConstantEntrymember,IEnumerable<GenBase>gens)
+WeakReferencecache_found_class;
+
+(GenBaseCls,FieldField)?FindManagedMember(EnumDescriptiondesc,ConstantEntryconstant,IEnumerable<GenBase>gens)
 {
 if(desc.FieldsRemoved)
 returnnull;
 
-varjniMember=member.JavaSignature;
+varjniMember=constant.JavaSignature;
+
 if(string.IsNullOrWhiteSpace(jniMember)){
 // enum values like "None" falls here.
 returnnull;
 }
-returnFindManagedMember(jniMember,gens);
-}
 
-WeakReferencecache_found_class;
+ParseJniMember(jniMember,outvarpackage,outvartype,outvarmember);
 
-stringFindManagedMember(stringjniMember,IEnumerable<GenBase>gens)
-{
-stringpackage,type,member;
-ParseJniMember(jniMember,outpackage,outtype,outmember);
 varfullJavaType=(string.IsNullOrEmpty(package)?"":package+".")+type;
 
 varcls=cache_found_class!=null?cache_found_class.TargetasGenBase:null;
@@ -96,7 +103,7 @@ string FindManagedMember (string jniMember, IEnumerable<GenBase> gens)
 // The field was not found e.g. removed by metadata fixup.
 returnnull;
 }
-returncls.FullName+"."+fld.Name;
+return(cls,fld);
 }
 
 internalvoidParseJniMember(stringjniMember,outstringpackage,outstringtype,outstringmember)

tools/generator/SourceWriters/Extensions/SourceWriterExtensions.cs

@@ -293,12 +293,14 @@ public static void AddParameterListCallArgs (List<string> body, ParameterList pa
 }
 
 publicstaticvoidAddSupportedOSPlatform(List<AttributeWriter>attributes,ApiVersionsSupport.IApiAvailabilitymember,CodeGenerationOptionsopt)
+=>AddSupportedOSPlatform(attributes,member.ApiAvailableSince,opt);
+
+publicstaticvoidAddSupportedOSPlatform(List<AttributeWriter>attributes,intsince,CodeGenerationOptionsopt)
 {
 // There's no sense in writing say 'android15' because we do not support older APIs,
 // so those APIs will be available in all of our versions.
-if(member.ApiAvailableSince>21&&opt.CodeGenerationTarget==Xamarin.Android.Binder.CodeGenerationTarget.XAJavaInterop1)
-attributes.Add(newSupportedOSPlatformAttr(member.ApiAvailableSince));
-
+if(since>21&&opt.CodeGenerationTarget==Xamarin.Android.Binder.CodeGenerationTarget.XAJavaInterop1)
+attributes.Add(newSupportedOSPlatformAttr(since));
 }
 
 publicstaticvoidAddObsolete(List<AttributeWriter>attributes,stringmessage,CodeGenerationOptionsopt,boolforceDeprecate=false,boolisError=false,int?deprecatedSince=null)