[Bindings.targets] Warn about deprecated jar2xml and XamarinAndroid values.

[jpobst]

Both <AndroidClassParser>jar2xml</AndroidClassParser> and <AndroidCodegenTarget>XamarinAndroid</AndroidCodegenTarget> were replaced 5+ years ago by class-parse and XAJavaInterop1 respectively.

We already are not adding new features to them, like DIM, NRT, and Kotlin improvements, so projects using them are not benefiting from our improvements.

We would also like to some day stop maintaining these configurations. As such, add warnings to Bindings project builds if these configurations are still used:

XA4231: The Android class parser value 'jar2xml' is deprecated and will be removed in 
a future version of Xamarin.Android. Update the project properties to use 'class-parse'.

XA4232: The Android code generation target 'XamarinAndroid' is deprecated and will 
be removed in a future version of Xamarin.Android. Update the project properties to 
use 'XAJavaInterop1'.

[jonathanpeppers]

Maybe these should be:

Suggested change

	<Target Name="_WarnAboutDeprecatedConfigurations">
	<AndroidWarning Code="XA4229"
	ResourceName="XA4229"
	FormatArguments="$(AndroidClassParser)"
	Condition=" '$(AndroidClassParser)' != 'class-parse' "
	/>
	<AndroidWarning Code="XA4230"
	ResourceName="XA4230"
	FormatArguments="$(AndroidCodegenTarget)"
	Condition=" '$(AndroidCodegenTarget)' != 'XAJavaInterop1' "
	/>
	</Target>
	<Target Name="_WarnAboutDeprecatedConfigurations">
	<AndroidWarning Code="XA4229"
	ResourceName="XA4229"
	FormatArguments="$(AndroidClassParser)"
	Condition=" '$(AndroidClassParser)' == 'jar2xml' "
	/>
	<AndroidWarning Code="XA4230"
	ResourceName="XA4230"
	FormatArguments="$(AndroidCodegenTarget)"
	Condition=" '$(AndroidCodegenTarget)' == 'XamarinAndroid' "
	/>
	</Target>

Just so that if we add a new value for these, we won't accidentally get warnings.

[jpobst]

I've seen a few cases of people using invalid values like Xamarin.Android so this covers them as well. Ideally we eventually just remove the properties completely. If we later need to bring them back with new values we may end up using different properties.

[jonpryor]

Suggested replacement:

The Android class parser '{0}' is deprecated and will be removed in a future version of Xamarin.Android. Update the $(AndroidClassParser) property to be 'class-parse'.

[jpobst]

I tried to keep the verbiage (Android class parser/Android code generator) close to the property pages, as I would expect most of our users to change it there instead of manually editing the .csproj file. Should we try to come up with a message that reflects this but also mentions the MSBuild equivalents as well?

[jonpryor]

Hm. Fair.

OK, then what about The Android class parser *value* '{0}'…? (Emphasis added, and not intended to be in the actual message.) Then, instead of mentioning the property at the end, mention that it can be changed in the Project Properties?

The Android class parser value '{0}' is deprecated and will be removed in a future version of Xamarin.Android. Update Project Properties to use class-parse.

[jonpryor]

Suggested replacement:

The Android code generator '{0}' is deprecated and will be removed in a future version of Xamarin.Android. Update the $(AndroidCodegenTarget) property to be 'XAJavaInterop1'.

[brendanzagaeski]

Draft release notes

Here's a candidate release note for this change based on similar previous cases. Feel free to suggest changes.

### Bindings projects XA4231 warning for deprecated jar2xml parser

Any bindings project that has the `AndroidClassParser` MSBuild property set to
the old `jar2xml` parser or any other unrecognized value will now get a XA4231
build warning:

```
warning XA4231: The Android class parser 'jar2xml' is deprecated and will be removed in a future version of Xamarin.Android. Update the project properties to use 'class-parse' instead.
```

To resolve this error, update the **Android Class Parser** setting in the Visual
Studio project property pages or the **.jar file parser** setting in Visual
Studio for Mac to **class-parse**.  This corresponds to the `class-parse` value
for the `AndroidClassParser` MSBuild property in the _.csproj_ file:

```xml
<PropertyGroup>
  <AndroidClassParser>class-parse</AndroidClassParser>
</PropertyGroup>
```

### Bindings projects XA4232 warning for deprecated XamarinAndroid code generation target

Any bindings project that has the `AndroidCodegenTarget` MSBuild property set to
the old `XamarinAndroid` code generation target or any other unrecognized value
will now get a XA4232 build warning:

```
warning XA4232: The Android code generation target value 'XamarinAndroid' is deprecated and will be removed in a future version of Xamarin.Android. Update the project properties to use 'XAJavaInterop1'.
```

To resolve this error, update the **Android Codegen target** setting in the
Visual Studio project property pages or the **Code generation target** setting
in Visual Studio for Mac to **XAJavaInterop1**.  This corresponds to the
`XAJavaInterop1` value for the `AndroidCodegenTarget` MSBuild property in the
_.csproj_ file:

```xml
<PropertyGroup>
  <AndroidCodegenTarget>XAJavaInterop1</AndroidCodegenTarget>
</PropertyGroup>
```

[brendanzagaeski]

• One tiny idea is to replace '$(AndroidClassParser)' with '{classParser}' and '$(AndroidCodegenTarget)' with '{codeGenerator}' to avoid mixing string interpolation styles in the README file (even though it's all "pretend" string interpolation anyway). Or maybe even simpler, since the invalid values in projects will usually be the known old values, I think it'd be OK to use the actual values in this case: 'jar2xml' and 'XamarinAndroid'

• It's not too important, but this README entries can also be updated slightly to match the new wording from the .resx file that mentions the project properties.

• If possible, it could also be good to add short little xa4231.md and xa4232.md files for these new messages. I haven't yet had a chance to add dedicated pages for many of the lines I recently added to the README for old existing messages, but if I'm remembering correctly, I think for new codes moving forward, JonP was in favor of having dedicated pages whenever possible. (I'll add a note about that to the Localization workflow doc along with your other good suggestions.)

  The files can just paste parts from the corresponding release notes to fill out the standard sections for those dedicated message pages.

[brendanzagaeski]

I'm pretty sure the current comment will work perfectly well for the l10n team, so this isn't really important, but there could be a small advantage in making it:

The following are literal names and should not be translated: class-parse

As I got further along in adding strings to the .resx for existing messages, I decided that whenever it didn't look confusing, I'd use that same phrase to indicate the "don't translate" items. One place I used a different comment was for a string containing a comma in XA4214_Result.

(I'll add these tips to the Localization doc along with your other good suggestions.)

[brendanzagaeski]

Since the UI menu item in Visual Studio (either via the Project menu or the context menu in the Solution Explorer) doesn't appear as the exact term "Project Properties," I'll suggest lowercase "project properties":

... Update the project properties to use 'class-parse'.

There's some precedent for that lowercase formatting in the Visual Studio docs, so it should be alright in terms of user familiarity.

[brendanzagaeski]

Maybe it would be OK to replace code generator with code generation target to help align with the IDE project property page wordings? This property appears as:

• Android Codegen Target in Visual Studio
• Code generation target in Visual Studio for Mac

[brendanzagaeski]

Hmm. Since "target value" is a common phrase that isn't applicable here, maybe it can be code generation target {0}:

<value>The Android code generation target '{0}' is deprecated and will be removed in a future version of Xamarin.Android. Update the project properties to use 'XAJavaInterop1'.</value>
<comment>The following are literal names and should not be translated: XAJavaInterop1
{0} - The name of the current code generation target</comment>

[brendanzagaeski]

Looks good! Thanks for bearing with me on the wording adjustments 😄