[ScriptingBridge] Remove outdated tests and add documentation. Fixes #21242. (#21246)

The test we had in our codebase for the SBApplication class was not only
outdated, but also incorrect.

With recent changes the test code doesn't work anymore, so delete it.

Instead, add XML documentation that explains how to use the class in a
way that works.

Fixes https://github.com/xamarin/xamarin-macios/issues/21242.

src/ScriptingBridge/SBApplication.cs

@@ -7,6 +7,43 @@ using Foundation;
 using ObjCRuntime;
 
 namespace ScriptingBridge {
+	/// <summary>This class provides API to send Apple events to scriptable applications and get Apple events back.</summary>
+	/// <remarks>
+	///   <para>There are multiple steps to use this API successfully.</para>
+	///   <para>First step is to create a binding project, which will define a protocol for the specific application to interact with, and the corresponding API. The code in the API definition for the binding project should look something like this:</para>
+	///   <example>
+	///     <code lang="csharp lang-csharp"><![CDATA[
+	/// namespace Finder {
+	///     [Protocol]
+	///     interface FinderApplication {
+	///         [Export ("version")]
+	///         string Version { get; }
+	///     }
+	/// }]]></code>
+	///   </example>
+	///   <para>The second step is to create an executable project, which references the binding project. Additionally, the executable project defines a class that mirrors the protocol from the binding project:</para>
+	///   <example>
+	///     <code lang="csharp lang-csharp"><![CDATA[
+	/// namespace Finder {
+	///     [Protocol]
+	///     class FinderApplication : SBApplication, IFinderApplication {
+	///         // This constructor so that the runtime can create an instance of this class from the
+	///         // Objetive-C object handle in the call to SBApplication.GetApplication.
+	///         protected FinderApplication (NativeHandle handle) { }
+	///         // Otherwise this class is empty, all the API will be provided through the protocol interface.
+	///     }
+	/// }]]></code>
+	///   </example>
+	///   <para>Note that the FinderApplication class subclasses this class (<see cref="SBApplication" />), in addition to implementing the FinderApplication protocol (which has been generated as an interface, with an <c>I</c> prefix, in the binding project).</para>
+	///   <para>The final step is to call GetApplication, and cast the return value to the protocol interface.</para>
+	///   <example>
+	///     <code lang="csharp lang-csharp"><![CDATA[
+	/// public static string GetFinderVersion () {
+	///     var finder = (IFinderApplication) SBApplication.GetApplication&lt;FinderApplication&gt; ("com.apple.finder");
+	///     return finder.Version;
+	/// }]]></code>
+	///   </example>
+	/// </remarks>
 	public partial class SBApplication {
 		public static SBApplication? GetApplication (string ident) => Runtime.GetNSObject<SBApplication> (_FromBundleIdentifier (ident));
 
@@ -19,25 +56,5 @@ namespace ScriptingBridge {
 		public static SBApplication? GetApplication (int pid) => Runtime.GetNSObject<SBApplication> (_FromProcessIdentifier (pid));
 
 		public static T? GetApplication<T> (int pid) where T : SBApplication => Runtime.GetINativeObject<T> (_FromProcessIdentifier (pid), forced_type: true, owns: false);
-
-#if !NET
-		[Obsolete ("Use 'GetApplication' instead.")]
-		public static SBApplication? FromBundleIdentifier (string ident) => Runtime.GetNSObject<SBApplication> (_FromBundleIdentifier (ident));
-
-		[Obsolete ("Use 'GetApplication' instead.")]
-		public static T? FromBundleIdentifier<T> (string ident) where T : SBApplication => Runtime.GetINativeObject<T> (_FromBundleIdentifier (ident), forced_type: true, owns: false);
-
-		[Obsolete ("Use 'GetApplication' instead.")]
-		public static SBApplication? FromURL (NSUrl url) => Runtime.GetNSObject<SBApplication> (_FromURL (url));
-
-		[Obsolete ("Use 'GetApplication' instead.")]
-		public static T? FromURL<T> (NSUrl url) where T : SBApplication => Runtime.GetINativeObject<T> (_FromURL (url), forced_type: true, owns: false);
-
-		[Obsolete ("Use 'GetApplication' instead.")]
-		public static SBApplication? FromProcessIdentifier (int pid) => Runtime.GetNSObject<SBApplication> (_FromProcessIdentifier (pid));
-
-		[Obsolete ("Use 'GetApplication' instead.")]
-		public static T? FromProcessIdentifier<T> (int pid) where T : SBApplication => Runtime.GetINativeObject<T> (_FromProcessIdentifier (pid), forced_type: true, owns: false);
-#endif
 	}
 }

tests/cecil-tests/Documentation.KnownFailures.txt

@@ -81348,7 +81348,6 @@ T:ScreenTime.STWebpageController
 T:ScriptingBridge.AESendMode
 T:ScriptingBridge.ISBApplicationDelegate
 T:ScriptingBridge.LSLaunchFlags
-T:ScriptingBridge.SBApplication
 T:ScriptingBridge.SBApplicationDelegate
 T:ScriptingBridge.SBApplicationError
 T:ScriptingBridge.SBElementArray

tests/scriptingbridge/Makefile

@@ -1,41 +0,0 @@
-TOP = ../..
-
-include $(TOP)/Make.config
-include $(TOP)/mk/rules.mk
-
-MMP=$(MAC_DESTDIR)/Library/Frameworks/Xamarin.Mac.framework/Versions/Current/bin/mmp
-BMAC=$(MAC_DESTDIR)/Library/Frameworks/Xamarin.Mac.framework/Versions/Current/bin/bmac
-
-all-local:: build/compat/test.app build/mobile-32/test.app build/mobile-64/test.app
-
-exec-compat: build/compat/test.app
-	./build/compat/test.app/Contents/MacOS/test | grep Passed
-
-exec-mobile-%: build/mobile-%/test.app
-	./build/mobile-$*/test.app/Contents/MacOS/test | grep Passed
-
-run run-test run-tests: build/compat/test.app build/mobile-32/test.app build/mobile-64/test.app
-	@rm -f .$@-failure.stamp
-	@$(MAKE) exec-compat    || echo "run-compat failed"    >> .$@-failure.stamp
-	@$(MAKE) exec-mobile-32 || echo "run-mobile-32 failed" >> .$@-failure.stamp
-	@$(MAKE) exec-mobile-64 || echo "run-mobile-64 failed" >> .$@-failure.stamp
-	@if test -e .$@-failure.stamp; then cat .$@-failure.stamp; rm .$@-failure.stamp; exit 1; fi
-
-build/compat/test.app: build/compat/finder.dll
-	rm -Rf $@
-	$(SYSTEM_CSC) "/out:build/compat/test.exe" "/r:build/compat/finder.dll" /r:$(TOP)/src/build/mac/compat/XamMac.dll /t:exe "test.cs" 
-	$(MMP) -nolink "-minos=10.9" -o "build/compat" -n "test" --profile "4.5" -a $(TOP)/src/build/mac/compat/XamMac.dll -a "build/compat/finder.dll" "build/compat/test.exe"
-
-build/compat/finder.dll:
-	$(BMAC) --out=build/compat/finder.dll --outdir=build/compat/ -r:/Library/Frameworks/Mono.framework/Versions/Current/lib/mono/4.5/System.Drawing.dll -baselib:$(TOP)/src/build/mac/compat/XamMac.dll finder.cs
-
-build/mobile-%/test.app: build/mobile-%/finder.dll
-	rm -Rf $@
-	$(SYSTEM_CSC) "/out:build/mobile-$*/test.exe" "/r:build/mobile-$*/finder.dll" /r:$(TOP)/src/build/mac/mobile-$*/Xamarin.Mac.dll /t:exe "test.cs"
-	$(MMP) -nolink "-minos=10.9" -o "build/mobile-$*" -n "test" --profile "4.5" -a $(TOP)/src/build/mac/mobile-$*/Xamarin.Mac.dll -a "build/mobile-$*/finder.dll" "build/mobile-$*/test.exe" --profile mobile --arch $(shell test '$*' == '32' && echo i386 || echo x86_64)
-
-build/mobile-%/finder.dll:
-	$(BMAC) --unified-mobile-profile --out=build/mobile-$*/finder.dll --outdir=build/mobile-$*/ -baselib:$(TOP)/src/build/mac/mobile-$*/Xamarin.Mac.dll finder.cs
-
-clean-local::
-	@rm -rf build/

tests/scriptingbridge/finder.cs

@@ -1,27 +0,0 @@
-using Foundation;
-using ObjCRuntime;
-using ScriptingBridge;
-
-namespace Finder {
-	[BaseType (typeof (SBObject))]
-	interface FinderItem {
-		[Export ("name")]
-		string Name { get; }
-	}
-
-	[BaseType (typeof (FinderItem))]
-	interface FinderContainer {
-	}
-
-	[BaseType (typeof (FinderContainer))]
-	interface FinderTrashObject {
-		[Export ("items")]
-		SBElementArray Items { get; }
-	}
-
-	[BaseType (typeof (SBApplication))]
-	interface FinderApplication {
-		[Export ("trash")]
-		FinderTrashObject Trash { get; }
-	}
-}

tests/scriptingbridge/test.cs

@@ -1,25 +0,0 @@
-using System;
-using Finder;
-using AppKit;
-using ScriptingBridge;
-
-namespace ScriptingBridge.Tests {
-	public static class MainClass {
-		static int Main (string [] args)
-		{
-			FinderApplication app = SBApplication.FromBundleIdentifier<FinderApplication> ("com.apple.finder");
-
-			if ((int) app.Trash.Items.Count > 0) {
-				for (int i = 0; i < (int) app.Trash.Items.Count; ++i) {
-					FinderItem item = app.Trash.Items.GetItem<FinderItem> ((nuint) i);
-					if (item.Name is null)
-						return 0;
-				}
-			}
-
-			Console.WriteLine ("Passed");
-
-			return 0;
-		}
-	}
-}