Improve xml comments review 5th DRAFT

Directory.Build.targets

@@ -3,9 +3,12 @@
   <Import Project="$(RepositoryEngineeringDir)Analyzer.targets" />
   <Import Project="Sdk.targets" Sdk="Microsoft.DotNet.Arcade.Sdk" />
   <Import Project="$(RepositoryEngineeringDir)packageContent.targets" />
-  <Import Project="$(RepositoryEngineeringDir)versioning.targets" />
   <Import Project="$(RepositoryEngineeringDir)Test.targets" Condition="'$(IsTestProject)' == 'true' "/>
 
+  <PropertyGroup>
+    <Description Condition="'$(Description)' == ''">$(AssemblyName)</Description>
+  </PropertyGroup>
+
   <!-- CA1416 Validate platform compatibility. Do not apply to netstandard as it does not have the attribute. -->
   <ItemGroup>
     <AssemblyAttribute Include="System.Runtime.Versioning.SupportedOSPlatform" Condition="!$(TargetFramework.StartsWith('netstandard'))">

pkg/Microsoft.Dotnet.WinForms.ProjectTemplates/content/WinFormsApplication-VisualBasic/ApplicationEvents.vb

@@ -3,15 +3,18 @@
 Namespace My
     ' The following events are available for MyApplication:
     ' Startup: Raised when the application starts, before the startup form is created.
-    ' Shutdown: Raised after all application forms are closed. This event is not raised if the application terminates abnormally.
+    ' Shutdown: Raised after all application forms are closed. This event is not raised if the
+    '           application terminates abnormally.
     ' UnhandledException: Raised if the application encounters an unhandled exception.
     ' StartupNextInstance: Raised when launching a single-instance application and the application is already active.
     ' NetworkAvailabilityChanged: Raised when the network connection is connected or disconnected.
 
-    ' **NEW** ApplyApplicationDefaults: Raised when the application queries default values to be set for the application.
+    ' **NEW** ApplyApplicationDefaults:
+    ' Raised when the application queries default values to be set for the application.
 
     ' Example:
-    ' Private Sub MyApplication_ApplyApplicationDefaults(sender As Object, e As ApplyApplicationDefaultsEventArgs) Handles Me.ApplyApplicationDefaults
+    ' Private Sub MyApplication_ApplyApplicationDefaults(sender As Object, e As ApplyApplicationDefaultsEventArgs) _
+    '    Handles Me.ApplyApplicationDefaults
     '
     '   ' Setting the application-wide default Font:
     '   e.Font = New Font(FontFamily.GenericSansSerif, 12, FontStyle.Regular)

src/Common/src/RTLAwareMessageBox.cs

@@ -4,7 +4,8 @@
 namespace System.Windows.Forms;
 
 /// <summary>
-///  The Show method displays a message box that can contain text, buttons, and symbols that inform and instruct the user.
+///  The Show method displays a message box that can contain text, buttons,
+///  and symbols that inform and instruct the user.
 ///  This MessageBox will be RTL, if the resources for this dll have been localized to a RTL language.
 /// </summary>
 internal sealed class RTLAwareMessageBox

src/Common/tests/TestUtilities/BinarySerialization.cs

@@ -75,7 +75,9 @@ static object FromByteArray(byte[] raw, FormatterAssemblyStyle assemblyStyle)
         {
 #pragma warning disable SYSLIB0011 // Type or member is obsolete
             // cs/binary-formatter-without-binder
-            BinaryFormatter binaryFormatter = new() // CodeQL [SM04191] : Safe use because the deserialization process is performed on trusted data and the types are controlled and validated.
+            // CodeQL [SM04191] : Safe use because the deserialization process is
+            // performed on trusted data and the types are controlled and validated.
+            BinaryFormatter binaryFormatter = new()
             {
                 AssemblyFormat = assemblyStyle
             };
@@ -84,7 +86,9 @@ static object FromByteArray(byte[] raw, FormatterAssemblyStyle assemblyStyle)
             using MemoryStream serializedStream = new(raw);
 
             // cs/dangerous-binary-deserialization
-            return binaryFormatter.Deserialize(serializedStream); // CodeQL[SM03722] : Testing legacy feature. This is a safe use of BinaryFormatter because the data is trusted and the types are controlled and validated.
+            // CodeQL[SM03722] : Testing legacy feature. This is a safe use of BinaryFormatter
+            // because the data is trusted and the types are controlled and validated.
+            return binaryFormatter.Deserialize(serializedStream);
         }
     }
 
@@ -103,7 +107,9 @@ static byte[] ToByteArray(object obj, FormatterAssemblyStyle assemblyStyle)
         {
 #pragma warning disable SYSLIB0011 // Type or member is obsolete
             // cs/binary-formatter-without-binder
-            BinaryFormatter binaryFormatter = new() // CodeQL [SM04191]: Safe use because the deserialization process is performed on trusted data and the types are controlled and validated.
+            // CodeQL [SM04191]: Safe use because the deserialization process is performed on trusted data and
+            // the types are controlled and validated.
+            BinaryFormatter binaryFormatter = new()
             {
                 AssemblyFormat = assemblyStyle
             };

src/Common/tests/TestUtilities/CustomConverter.cs

@@ -24,7 +24,9 @@ public static RegistrationScope RegisterConverter(Type type, TypeConverter conve
     /// <summary>
     ///  Manages the registration lifetime of a TypeConverter to a type.
     ///  This is meant to be utilized in a <see langword="using"/> statement to ensure
-    ///  <see cref="TypeDescriptor.RemoveProvider(TypeDescriptionProvider, Type)"/> is called when going out of scope with the using.
+    ///  <see cref="TypeDescriptor.RemoveProvider(TypeDescriptionProvider, Type)">
+    ///   is called when going out of scope with the using.
+    ///  </see>
     /// </summary>
     public readonly ref struct RegistrationScope
     {

src/Common/tests/TestUtilities/DebuggerAttributes.cs

@@ -73,7 +73,8 @@ public static IEnumerable<FieldInfo> GetDebuggerVisibleFields(Type debuggerAttri
 
     public static IEnumerable<PropertyInfo> GetDebuggerVisibleProperties(Type debuggerAttributeType)
     {
-        // The debugger doesn't evaluate non-public members of type proxies. GetGetMethod returns null if the getter is non-public.
+        // The debugger doesn't evaluate non-public members of type proxies.
+        // GetGetMethod returns null if the getter is non-public.
         IEnumerable<PropertyInfo> visibleProperties = debuggerAttributeType.GetProperties()
             .Where(pi => pi.GetGetMethod() is not null && GetDebuggerBrowsableState(pi) != DebuggerBrowsableState.Never);
         return visibleProperties;

src/Common/tests/TestUtilities/TempFile.cs

@@ -17,7 +17,9 @@ namespace System.IO;
 /// </remarks>
 public sealed class TempFile : IDisposable
 {
-    /// <summary>Gets the created file's path.</summary>
+    /// <summary>
+    ///  Gets the created file's path.
+    /// </summary>
     public string Path { get; }
 
     public TempFile(string path, long length = 0) : this(path, length > -1 ? new byte[length] : null)

src/Common/tests/TestUtilities/XUnit/UseCultureAttribute.cs

@@ -1,7 +1,8 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-// The original code was borrowed from https://github.com/xunit/samples.xunit/blob/93f87d5/UseCulture/UseCultureAttribute.cs
+// The original code was borrowed from
+// https://github.com/xunit/samples.xunit/blob/93f87d5/UseCulture/UseCultureAttribute.cs
 // Licensed under http://www.apache.org/licenses/LICENSE-2.0.
 
 using System.Globalization;
@@ -13,7 +14,8 @@ namespace Xunit;
 
 /// <summary>
 ///  Apply this attribute to your test method to replace the <see cref="Thread.CurrentThread" />
-///  <see cref="CultureInfo.CurrentCulture" /> and <see cref="CultureInfo.CurrentUICulture" /> with another culture.
+///  <see cref="CultureInfo.CurrentCulture" /> and
+///  <see cref="CultureInfo.CurrentUICulture" /> with another culture.
 /// </summary>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
 public class UseCultureAttribute : BeforeAfterTestAttribute
@@ -31,14 +33,17 @@ public class UseCultureAttribute : BeforeAfterTestAttribute
     /// <summary>
     ///  Replaces the culture and UI culture of the current thread with <paramref name="culture" />.
     /// </summary>
-    /// <param name="culture">The name of the culture to set for both <see cref="Culture" /> and <see cref="UICulture" />.</param>
+    /// <param name="culture">
+    ///  The name of the culture to set for both <see cref="Culture" /> and <see cref="UICulture" />.
+    /// </param>
     public UseCultureAttribute(string culture)
         : this(culture, culture)
     {
     }
 
     /// <summary>
-    ///  Replaces the culture and UI culture of the current thread with <paramref name="culture" /> and <paramref name="uiCulture" />.
+    ///  Replaces the culture and UI culture of the current thread with
+    ///  <paramref name="culture" /> and <paramref name="uiCulture" />.
     /// </summary>
     /// <param name="culture">The name of the culture.</param>
     /// <param name="uiCulture">The name of the UI culture.</param>

src/Microsoft.VisualBasic.Forms/src/Microsoft.VisualBasic.Forms.vbproj

@@ -18,6 +18,10 @@
     <UsePublicApiAnalyzers>true</UsePublicApiAnalyzers>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Compile Remove="Microsoft\VisualBasic\MyServices\Internal\WebClientCopy.vb" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\..\System.Windows.Forms\src\System.Windows.Forms.csproj" />
   </ItemGroup>

src/Microsoft.VisualBasic.Forms/src/Microsoft/VisualBasic/ApplicationServices/ApplicationBase.vb

@@ -16,7 +16,7 @@ Namespace Microsoft.VisualBasic.ApplicationServices
         ' The executing application (the EntryAssembly)
         Private _info As AssemblyInfo
 
-        'Lazy-initialized and cached log object.
+        ' Lazy-initialized and cached log object.
         Private _log As Logging.Log
 
         Public Sub New()
@@ -38,7 +38,9 @@ Namespace Microsoft.VisualBasic.ApplicationServices
         Public ReadOnly Property Info() As AssemblyInfo
             Get
                 If _info Is Nothing Then
-                    Dim assembly As Reflection.Assembly = If(Reflection.Assembly.GetEntryAssembly(), Reflection.Assembly.GetCallingAssembly())
+                    Dim assembly As Reflection.Assembly =
+                        If(Reflection.Assembly.GetEntryAssembly(), Reflection.Assembly.GetCallingAssembly())
+
                     _info = New AssemblyInfo(assembly)
                 End If
                 Return _info

src/Microsoft.VisualBasic.Forms/src/Microsoft/VisualBasic/ApplicationServices/CantStartSingleInstanceException.vb

@@ -2,6 +2,7 @@
 ' The .NET Foundation licenses this file to you under the MIT license.
 
 Imports System.ComponentModel
+Imports System.Runtime.Serialization
 
 Imports VbUtils = Microsoft.VisualBasic.CompilerServices.ExceptionUtils
 
@@ -18,27 +19,27 @@ Namespace Microsoft.VisualBasic.ApplicationServices
         ' Deserialization constructor must be defined since we are serializable
         <EditorBrowsable(EditorBrowsableState.Advanced)>
         <Obsolete("Type or member is obsolete", DiagnosticId:="SYSLIB0051")>
-        Protected Sub New(info As Runtime.Serialization.SerializationInfo, context As Runtime.Serialization.StreamingContext)
+        Protected Sub New(info As SerializationInfo, context As StreamingContext)
             MyBase.New(info, context)
         End Sub
 
         ''' <summary>
-        '''  Creates a new <see cref="Exception"/>.
+        '''  Creates a new <see cref="CantStartSingleInstanceException"/>.
         ''' </summary>
         Public Sub New()
             MyBase.New(VbUtils.GetResourceString(SR.AppModel_SingleInstanceCantConnect))
         End Sub
 
         ''' <summary>
-        '''  Creates a new <see cref="Exception"/>.
+        '''  Creates a new <see cref="CantStartSingleInstanceException"/>.
         ''' </summary>
         ''' <inheritdoc cref="Exception.New(String)"/>
         Public Sub New(message As String)
             MyBase.New(message)
         End Sub
 
         ''' <summary>
-        '''  Creates a new <see cref="Exception"/>.
+        '''  Creates a new <see cref="CantStartSingleInstanceException"/>.
         ''' </summary>
         ''' <inheritdoc cref="Exception.New(String, Exception)"/>
         Public Sub New(message As String, inner As Exception)

src/Microsoft.VisualBasic.Forms/src/Microsoft/VisualBasic/ApplicationServices/ConsoleApplicationBase.vb

@@ -42,6 +42,9 @@ Namespace Microsoft.VisualBasic.ApplicationServices
         ''' <summary>
         '''  Returns the command line arguments for the current application.
         ''' </summary>
+        ''' <value>
+        '''  A <see cref="ObjectModel.ReadOnlyCollection(Of String)"/> containing the command line arguments
+        ''' </value>
         ''' <remarks>
         '''  This function differs from <see cref="Environment.GetCommandLineArgs"/>
         '''  in that the path of the executing file (the 0th entry) is omitted from
@@ -50,14 +53,28 @@ Namespace Microsoft.VisualBasic.ApplicationServices
         Public ReadOnly Property CommandLineArgs() As ObjectModel.ReadOnlyCollection(Of String)
             Get
                 If _commandLineArgs Is Nothing Then
-                    'Get rid of Arg(0) which is the path of the executing program. Main(args() as string) doesn't report the name of the app and neither will we
+                    ' Get rid of Arg(0) which is the path of the executing program. Main(args() as string)
+                    ' doesn't report the name of the app and neither will we
                     Dim envArgs As String() = Environment.GetCommandLineArgs
-                    If envArgs.GetLength(0) >= 2 Then '1 element means no args, just the executing program. >= 2 means executing program + one or more command line arguments
-                        Dim newArgs(envArgs.GetLength(0) - 2) As String 'dimming z(0) gives a z() of 1 element.
-                        Array.Copy(envArgs, 1, newArgs, 0, envArgs.GetLength(0) - 1) 'copy everything but the 0th element (the path of the executing program)
+
+                    ' 1 element means no args, just the executing program.
+                    If envArgs.GetLength(0) >= 2 Then
+                        ' >= 2 means executing program + one or more command line arguments
+                        ' dimming z(0) gives a z() of 1 element.
+                        Dim newArgs(envArgs.GetLength(0) - 2) As String
+
+                        ' Copy everything but the 0th element (the path of the executing program)
+                        Dim length As Integer = envArgs.GetLength(0) - 1
+                        Array.Copy(
+                            sourceArray:=envArgs,
+                            sourceIndex:=1,
+                            destinationArray:=newArgs,
+                            destinationIndex:=0,
+                            length)
                         _commandLineArgs = New ObjectModel.ReadOnlyCollection(Of String)(newArgs)
                     Else
-                        _commandLineArgs = New ObjectModel.ReadOnlyCollection(Of String)(Array.Empty(Of String)())  'provide the empty set
+                        ' Provide the empty set
+                        _commandLineArgs = New ObjectModel.ReadOnlyCollection(Of String)(Array.Empty(Of String)())
                     End If
                 End If
                 Return _commandLineArgs