[docs] Fix a few issues with the api docs. (#21932)

* Fix `see` tags (there's no "cfref" attribute, it's "cref") * Fix `seealso` tags, they shouldn't be nested inside other tags. * Simplify a few "cref" tags. * Remove the "block" tag, there's no such thing. * General formatting improvements.
dotnet · Jan 10, 2025 · 770dc84 · 770dc84
1 parent 2814e55
commit 770dc84
Show file tree

Hide file tree

Showing 5 changed files with 52 additions and 28 deletions.
diff --git a/docs/api/UIKit/UIAlertView.xml b/docs/api/UIKit/UIAlertView.xml
@@ -1,36 +1,55 @@
 <Documentation>
   <Docs DocId="T:UIKit.UIAlertView">
-    <summary>A <see cref="T:UIKit.UIView" /> that displays a dialog message with one or more buttons. (As of iOS 8, devs should use <see cref="T:UIKit.UIAlertController" /> rather than this class.)</summary>
+    <summary>
+      A <see cref="UIView" /> that displays a dialog message with one or more buttons.
+      (As of iOS 8, devs should use <see cref="UIAlertController" /> rather than this class.)
+    </summary>
     <remarks>
-      <para>As of iOS 8, app devs should use <see cref="T:UIKit.UIAlertController" /> rather than this class. Extensions may not use this class at all.</para>
       <para>
-        The <see cref="T:UIKit.UIAlertView" /> allows the application user to choose among alternative actions. The following code and image, taken from the "AlertViews" section of the "ios Standard Controls" sample illustrates the simplest use-case:
+        As of iOS 8, app devs should use <see cref="UIAlertController" /> rather than this class.
+        Extensions may not use this class at all.
+      </para>
+      <para>
+        The <see cref="UIAlertView" /> allows the application user to choose among alternative actions.
+        The following code and image, taken from the "AlertViews" section of the "ios Standard Controls"
+        sample illustrates the simplest use-case:
       </para>
       <example>
         <code lang="csharp lang-csharp"><![CDATA[
-UIAlertView alert = new UIAlertView () { 
-	Title = "alert title", Message = "this is a simple alert"
+var alert = new UIAlertView () {
+	Title = "alert title",
+  Message = "this is a simple alert"
 };
-alert.AddButton("OK");
+alert.AddButton ("OK");
 alert.Show ();
         ]]></code>
       </example>
       <para>
-        <img href="~/UIKit/_images/UIKit.UIAlertView.png" alt="Screenshot showing the alert view" />
+        An alternative to the <see cref="UIAlertView" /> is the <see cref="UIActionSheet" />.
       </para>
-      <para>An alternative to the <see cref="T:UIKit.UIAlertView" /> is the <see cref="T:UIKit.UIActionSheet" />.</para>
-      <para>The application developer can use <see cref="T:UIKit.UIAlertViewStyle" />s such as <see cref="F:UIKit.UIAlertViewStyle.PlainTextInput" /> or <see cref="F:UIKit.UIAlertViewStyle.LoginAndPasswordInput" /> to allow the application user to enter values.</para>
       <para>
-   The Xamarin API supports two styles of event notification: the Objective-C style that uses a delegate class or the C# style using event notifications.  
-</para>
+        The application developer can use <see cref="UIAlertViewStyle" />s such as <see cref="UIAlertViewStyle.PlainTextInput" />
+        or <see cref="UIAlertViewStyle.LoginAndPasswordInput" /> to allow the application user to enter values.
+      </para>
+      <para>
+        The managed API supports two styles of event notification: the Objective-C style that uses a delegate class or the C# style using event notifications.
+      </para>
       <para>
-   The C# style allows the user to add or remove event handlers at runtime by assigning to the events of properties of this class.    Event handlers can be anyone of a method, an anonymous methods or a lambda expression.  Using the C# style events or properties will override any manual settings to the Objective-C Delegate or WeakDelegate settings.
-</para>
-      <para>The Objective-C style requires the user to create a new class derived from <see cref="T:UIKit.UIAlertViewDelegate" /> class and assign it to the <format type="text/html"><a href="https://docs.microsoft.com/en-us/search/index?search=UIKit%20Delegate&amp;scope=Xamarin" title="P:UIKit.Delegate">P:UIKit.Delegate</a></format> property.   Alternatively, for low-level control, by creating a class derived from <see cref="T:Foundation.NSObject" /> which has every entry point properly decorated with an [Export] attribute.   The instance of this object can then be assigned to the <see cref="P:UIKit.UIAlertView.WeakDelegate" /> property.   
+        The C# style allows the user to add or remove event handlers at runtime by assigning to the
+        events of properties of this class. Event handlers can be anyone of a method, an anonymous method
+        or a lambda expression. Using the C# style events or properties will override any manual settings
+        to the Objective-C Delegate or WeakDelegate settings.
       </para>
-      <block subset="none" type="overrides">
+      <para>
+        The Objective-C style requires the user to create a new class derived from <see cref="UIAlertViewDelegate" />
+        class and assign it to the <see cref="Delegate" /> property. Alternatively, for low-level control, by creating
+        a class derived from <see cref="NSObject" /> which has every entry point properly decorated with an
+        <see cref="ExportAttribute" /> attribute and assigning an instance of this class to the <see cref="WeakDelegate" />
+        property.
+      </para>
+      <para>
         <para>This class should not be subclassed.</para>
-      </block>
+      </para>
     </remarks>
     <related type="externalDocumentation" href="https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIAlertView_Class/index.html">Apple documentation for <c>UIAlertView</c></related>
   </Docs>

diff --git a/docs/api/UIKit/UIDocument.xml b/docs/api/UIKit/UIDocument.xml
@@ -2,14 +2,24 @@
   <Docs DocId="T:UIKit.UIDocument">
     <summary>Abstract base class providing local and cloud-based management of Model data.</summary>
     <remarks>
-      <para>Application developers can subclass <see cref="T:UIKit.UIDocument" /> to create objects that are "Model-Controllers" and relate to Model (domain) objects analogously to how <see cref="T:UIKit.UIViewController" /> relate to <see cref="T:UIKit.UIView" />s. iOS provides a number of functions, including background asynchronous reading and writing of application data, automatic and safe data-saving, storage that is automatically coordinated between the application sandbox and cloud services, etc.</para>
-      <block subset="none" type="inheritors">
-        <para>At a minimum, application developers need to implement <see cref="M:UIKit.UIDocument.ContentsForType(System.String,Foundation.NSError@)" /> (for storage) and <see cref="M:UIKit.UIDocument.LoadFromContents(Foundation.NSObject,System.String,Foundation.NSError@)" /> (for retrieval). Additionally, application developers need to manage the lifecyle of the <see cref="T:UIKit.UIDocument" /> and this requires the application developer to set the preferred storage location, create a file URL, and discover, open, and close the file. Application developers should also track changes and resolve conflicts between document versions.</para>
-      </block>
-      <para tool="threads">The members of this class can be used from a background thread.</para>
+      <para>
+        Application developers can subclass <see cref="UIDocument" /> to create objects that are "Model-Controllers" and
+        relate to Model (domain) objects analogously to how <see cref="UIViewController" /> relate to <see cref="UIView" />s.
+        UIKit provides a number of functions, including background asynchronous reading and writing of application data,
+        automatic and safe data-saving, storage that is automatically coordinated between the application sandbox and cloud services, etc.
+      </para>
+      <para>
+        At a minimum, application developers need to implement <see cref="ContentsForType(string,out NSError)" /> (for storage) and
+        <see cref="LoadFromContents(NSObject,string,out NSError)" /> (for retrieval). Additionally, application developers need to
+        manage the lifecyle of the <see cref="UIDocument" /> and this requires the application developer to set the preferred storage
+        location, create a file URL, and discover, open, and close the file. Application developers should also track changes and resolve
+        conflicts between document versions.
+      </para>
+      <para>
+        The members of this class can be used from a background thread.
+      </para>
     </remarks>
     <related type="article" href="https://github.com/conceptdev/taskcloud">TaskCloud</related>
-
     <related type="externalDocumentation" href="https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIDocument_Class/index.html">Apple documentation for <c>UIDocument</c></related>
   </Docs>
 </Documentation>
diff --git a/src/ObjCRuntime/BlockCallbackAttribute.cs b/src/ObjCRuntime/BlockCallbackAttribute.cs
@@ -5,9 +5,7 @@ namespace ObjCRuntime {
 	/// This attribute is applied to delegate parameters in a delegate to specify
 	/// that the delegate parameter needs an Objective-C Block-style bridge.
 	/// </summary>
-	/// <remarks>
 	/// <seealso cref='T:ObjCRuntime.CCallbackAttribute' />
-	/// </remarks>
 	[AttributeUsage (AttributeTargets.Parameter, AllowMultiple = false)]
 	public class BlockCallbackAttribute : Attribute {
 		/// <summary>

diff --git a/src/ObjCRuntime/CCallbackAttribute.cs b/src/ObjCRuntime/CCallbackAttribute.cs
@@ -5,9 +5,7 @@ namespace ObjCRuntime {
 	/// This attribute is applied to delegate parameters in a delegate to specify
 	/// that the delegate parameter needs an C-style bridge.
 	/// </summary>
-	/// <remarks>
 	/// <seealso cref='T:ObjCRuntime.BlockCallbackAttribute' />
-	/// </remarks> 
 	[AttributeUsage (AttributeTargets.Parameter, AllowMultiple = false)]
 	public class CCallbackAttribute : Attribute {
 		/// <summary>

diff --git a/src/authenticationservices.cs b/src/authenticationservices.cs
@@ -279,8 +279,7 @@ interface ASCredentialIdentityStoreState {
 	/// <summary>Delegate object for completion handlers in methods within <format type="text/html"><a href="https://docs.microsoft.com/en-us/search/index?search=Authentication%20Services%20ASCredential%20Provider%20Extension&amp;scope=Xamarin" title="T:AuthenticationServices.ASCredentialProviderExtension">T:AuthenticationServices.ASCredentialProviderExtension</a></format>.</summary>
 	delegate void ASCredentialProviderExtensionRequestCompletionHandler (bool expired);
 
-	/// <summary>
-	///       <see cfref="T:Foundation.NSExtensionContext" /> subclass that provides context for a credential provider.</summary>
+	/// <summary>An <see cref="NSExtensionContext" /> subclass that provides context for a credential provider.</summary>
 	[Introduced (PlatformName.MacCatalyst, 14, 0)]
 	[NoTV]
 	[NoWatch]