From 253384eee5cda274b972caaade8052b53d2ebbc6 Mon Sep 17 00:00:00 2001
From: Matt Connew <mconnew@users.noreply.github.com>
Date: Thu, 6 Jul 2023 16:51:40 -0700
Subject: [PATCH] Make Federation package generate documentation file. Fix some
 doc formatting bugs

---
 .../src/System.ServiceModel.Federation.csproj             | 1 +
 .../ServiceModel/Federation/IWSTrustChannelContract.cs    | 1 -
 .../src/System/ServiceModel/Federation/WSTrustChannel.cs  | 4 ++--
 .../System/ServiceModel/Federation/WSTrustUtilities.cs    | 3 +++
 .../ServiceModel/Federation/WsFederationHttpBinding.cs    | 4 ++--
 .../Federation/WsTrustChannelClientCredentials.cs         | 4 ++--
 .../ServiceModel/Federation/WsTrustTokenParameters.cs     | 8 +++++---
 7 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/src/System.ServiceModel.Federation/src/System.ServiceModel.Federation.csproj b/src/System.ServiceModel.Federation/src/System.ServiceModel.Federation.csproj
index 3103de51089..4df54836041 100644
--- a/src/System.ServiceModel.Federation/src/System.ServiceModel.Federation.csproj
+++ b/src/System.ServiceModel.Federation/src/System.ServiceModel.Federation.csproj
@@ -8,6 +8,7 @@
     <IsShipping>$(Ship_WcfPackages)</IsShipping>
     <TargetFramework>net6.0</TargetFramework>
     <PackageDescription>Provides the types that allow security communications with SOAP messages using WS-Federation.</PackageDescription>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>
diff --git a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/IWSTrustChannelContract.cs b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/IWSTrustChannelContract.cs
index e012e0dd3ae..b01df3648c5 100644
--- a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/IWSTrustChannelContract.cs
+++ b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/IWSTrustChannelContract.cs
@@ -19,7 +19,6 @@ public interface IWSTrustChannelContract
         /// </summary>
         /// <param name="request">The <see cref="WsTrustRequest" /> to send to the STS.</param>
         /// <returns>A <see cref="SecurityToken" /> issued by the STS.</returns>
-        /// <summary>
         [OperationContract(Name = "Issue", Action = "*", ReplyAction = "*")]
         Task<SecurityToken> IssueAsync(WsTrustRequest request);
     }
diff --git a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WSTrustChannel.cs b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WSTrustChannel.cs
index f266a4f5091..e334ef1d4a7 100644
--- a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WSTrustChannel.cs
+++ b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WSTrustChannel.cs
@@ -81,7 +81,7 @@ protected virtual Message CreateRequest(WsTrustRequest trustRequest)
         /// <summary>
         /// Gets the WS-Addressing SOAP action that corresponds to the <see cref="WsTrustRequest"/>.RequestType and <see cref="WsTrustRequest"/>.WsTrustVersion.
         /// </summary>
-        /// <param name="trustRequest">The <see cref="WsTrustRequest"/> to generate the WS-Addressing action.
+        /// <param name="trustRequest">The <see cref="WsTrustRequest"/> to generate the WS-Addressing action.</param>
         /// <returns>The WS-Addressing action to use.</returns>
         public static string GetRequestAction(WsTrustRequest trustRequest)
         {
@@ -112,7 +112,7 @@ public static string GetRequestAction(WsTrustRequest trustRequest)
         /// <summary>
         /// Gets the <see cref="WsSerializationContext"/> to use when serializing the <see cref="WsTrustRequest"/>.
         /// </summary>
-        /// <param name="trustRequest">The <see cref="WsTrustRequest"/> that will be serialized.
+        /// <param name="trustRequest">The <see cref="WsTrustRequest"/> that will be serialized.</param>
         /// <returns>The <see cref="WsSerializationContext"/> for the <see cref="WsTrustRequest"/>.</returns>
         private WsSerializationContext GetSerializationContext(WsTrustRequest trustRequest)
         {
diff --git a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WSTrustUtilities.cs b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WSTrustUtilities.cs
index a301f0f33d4..25226a9e2c8 100644
--- a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WSTrustUtilities.cs
+++ b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WSTrustUtilities.cs
@@ -20,6 +20,7 @@ namespace System.ServiceModel.Federation
     /// </summary>
     internal static class WSTrustUtilities
     {
+        /// <summary>
         /// Get a proof token from a WsTrust request/response pair based on section 4.4.3 of the WS-Trust 1.3 spec.
         /// How the proof token is retrieved depends on whether the requester or issuer provide key material:
         /// Requester   |   Issuer                  | Results
@@ -32,6 +33,8 @@ internal static class WSTrustUtilities
         /// </summary>
         /// <param name="request">The WS-Trust request (RST).</param>
         /// <param name="response">The WS-Trust response (RSTR).</param>
+        /// <param name="serializationContext">The serialization context.</param>
+        /// <param name="algorithmSuite">The algorithm suite.</param>
         /// <returns>The proof token or null if there is no proof token.</returns>
         internal static BinarySecretSecurityToken GetProofToken(WsTrustRequest request, Microsoft.IdentityModel.Protocols.WsTrust.RequestSecurityTokenResponse response, WsSerializationContext serializationContext, SecurityAlgorithmSuite algorithmSuite)
         {
diff --git a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsFederationHttpBinding.cs b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsFederationHttpBinding.cs
index 1049a5e185b..ba6d6c30b89 100644
--- a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsFederationHttpBinding.cs
+++ b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsFederationHttpBinding.cs
@@ -45,8 +45,8 @@ public WSTrustTokenParameters WSTrustTokenParameters
         /// </summary>
         /// <returns>a <see cref="SecurityBindingElement"/> for the RelyingParty channel.</returns>
         /// <remarks>Creates a new <see cref="TransportBindingElement"/> and adds <see cref="WSTrustTokenParameters"/> to the appropriate EndpointSupportingTokenParameters (Endorsing or Signed).
-        /// <para>Sets: <see cref="MessageSecurityVersion"/> == <see cref="WSTrustTokenParameters.MessageSecurityVersion"/>.</para></para>
-        /// <para>Sets: <see cref="IncludeTimestamp"/> == true.</para></remarks>
+        /// <para>Sets: <see cref="SecurityBindingElement.MessageSecurityVersion"/> == <see cref="WSTrustTokenParameters.MessageSecurityVersion"/>.</para>
+        /// <para>Sets: <see cref="SecurityBindingElement.IncludeTimestamp"/> == true.</para></remarks>
         protected override SecurityBindingElement CreateMessageSecurity()
         {
             WSTrustTokenParameters.RequireDerivedKeys = false;
diff --git a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsTrustChannelClientCredentials.cs b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsTrustChannelClientCredentials.cs
index 3661fb77e61..838bade5107 100644
--- a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsTrustChannelClientCredentials.cs
+++ b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsTrustChannelClientCredentials.cs
@@ -36,7 +36,7 @@ protected WSTrustChannelClientCredentials(WSTrustChannelClientCredentials other)
         /// Crates an instance of <see cref="WSTrustChannelClientCredentials"/> with specifying a <see cref="ClientCredentials"/>
         /// </summary>
         /// <param name="clientCredentials">The <see cref="SecurityTokenManager"/> from this parameter will be used to
-        /// create the <see cref="SecurityTokenProvider"/> in the case the <see cref="SecurityTokenParameters"/> in the channel are not a <see cref="WSTrustTokenParameters"/></para></remarks>
+        /// create the <see cref="SecurityTokenProvider"/> in the case the <see cref="System.ServiceModel.Security.Tokens.SecurityTokenParameters"/> in the channel are not a <see cref="WSTrustTokenParameters"/></param>
         public WSTrustChannelClientCredentials(ClientCredentials clientCredentials)
             : base(clientCredentials)
         {
@@ -62,7 +62,7 @@ protected override ClientCredentials CloneCore()
         /// </summary>
         /// <remarks>The <see cref="SecurityTokenManager"/> is responsible to return the <see cref="SecurityTokenProvider"/> to obtain the issued token.
         /// <para>If <see cref="ClientCredentials"/> was passed to the constructor, then that <see cref="SecurityTokenManager"/> will be used to
-        /// create the <see cref="SecurityTokenProvider"/> in the case the <see cref="SecurityTokenParameters"/> in the channel are not a <see cref="WSTrustTokenParameters"/></para></remarks>
+        /// create the <see cref="SecurityTokenProvider"/> in the case the <see cref="System.ServiceModel.Security.Tokens.SecurityTokenParameters"/> in the channel are not a <see cref="WSTrustTokenParameters"/></para></remarks>
         /// <returns>An instance of <see cref="WSTrustChannelSecurityTokenManager" />.</returns>
         public override SecurityTokenManager CreateSecurityTokenManager()
         {
diff --git a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsTrustTokenParameters.cs b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsTrustTokenParameters.cs
index 0420ffa3a6f..14b34f4fb7a 100644
--- a/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsTrustTokenParameters.cs
+++ b/src/System.ServiceModel.Federation/src/System/ServiceModel/Federation/WsTrustTokenParameters.cs
@@ -31,10 +31,12 @@ public class WSTrustTokenParameters : IssuedSecurityTokenParameters
         private int _issuedTokenRenewalThresholdPercentage = DefaultIssuedTokenRenewalThresholdPercentage;
 
         /// <summary>
-        /// Instantiates a <see cref="wsTrustTokenParameters"/> that describe the parameters for a WSTrust request.
+        /// Instantiates a <see cref="WSTrustTokenParameters"/> that describe the parameters for a WSTrust request.
         /// </summary>
-        /// <remarks><see cref="KeyType"/> == <see cref="SecurityKeyType.SymmetricKey"/>.
-        /// <para><see cref="MessageSecurityVersion"/> == <see cref="MessageSecurityVersion.WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10"/></para></remarks>
+        /// <remarks>
+        /// <para>Sets: <see cref="IssuedSecurityTokenParameters.KeyType"/> == <see cref="SecurityKeyType.SymmetricKey"/>.</para>
+        /// <para>Sets: <see cref="IssuedSecurityTokenParameters.DefaultMessageSecurityVersion"/> == <see cref="MessageSecurityVersion.WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10"/></para>
+        /// <para>Sets: <see cref="MessageSecurityVersion"/> == <see cref="MessageSecurityVersion.WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10"/></para></remarks>
         public WSTrustTokenParameters()
         {
             KeyType = DefaultSecurityKeyType;