Remove link attribute and use a comment instead (#248)

Author: SimonCropp

contributing.md

@@ -160,7 +160,7 @@ using Link = System.ComponentModel.DescriptionAttribute;
 /// The specification for module initializers in the .NET runtime can be found here:
 /// https://github.com/dotnet/runtime/blob/master/docs/design/specs/Ecma-335-Augments.md#module-initializer
 /// </remarks>
-[Link("https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.moduleinitializerattribute")]
+//Link: https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.moduleinitializerattribute
 [ExcludeFromCodeCoverage]
 [DebuggerNonUserCode]
 [AttributeUsage(
@@ -216,7 +216,7 @@ static partial class Polyfill
     /// <returns>A <see cref="Task"/> that represents the asynchronous flush operation.</returns>
     /// <exception cref="ObjectDisposedException">The text writer is disposed.</exception>
     /// <exception cref="InvalidOperationException">The writer is currently in use by a previous write operation.</exception>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.flushasync#system-io-textwriter-flushasync(system-threading-cancellationtoken)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.flushasync#system-io-textwriter-flushasync(system-threading-cancellationtoken)
     public static Task FlushAsync(this TextWriter target, CancellationToken cancellationToken)
     {
         if (cancellationToken.IsCancellationRequested)
@@ -236,7 +236,7 @@ static partial class Polyfill
     /// StringBuilder.GetChunks() method to avoid creating the intermediate string
     /// </summary>
     /// <param name="value">The string (as a StringBuilder) to write to the stream</param>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.write#system-io-textwriter-write(system-text-stringbuilder)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.write#system-io-textwriter-write(system-text-stringbuilder)
     public static void Write(this TextWriter target, StringBuilder? value)
     {
         if (value == null)
@@ -260,7 +260,7 @@ static partial class Polyfill
     /// </summary>
     /// <param name="value">The string (as a StringBuilder) to write to the stream</param>
     /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writeasync#system-io-textwriter-writeasync(system-readonlymemory((system-char))-system-threading-cancellationtoken)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writeasync#system-io-textwriter-writeasync(system-readonlymemory((system-char))-system-threading-cancellationtoken)
     public static Task WriteAsync(this TextWriter target, StringBuilder? value, CancellationToken cancellationToken = default)
     {
         if (cancellationToken.IsCancellationRequested)
@@ -302,7 +302,7 @@ static partial class Polyfill
     /// The default value is <see cref="CancellationToken.None"/>.
     /// </param>
     /// <returns>A task that represents the asynchronous write operation.</returns>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writeasync#system-io-textwriter-writeasync(system-readonlymemory((system-char))-system-threading-cancellationtoken)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writeasync#system-io-textwriter-writeasync(system-readonlymemory((system-char))-system-threading-cancellationtoken)
     public static ValueTask WriteAsync(
         this TextWriter target,
         ReadOnlyMemory<char> buffer,
@@ -330,7 +330,7 @@ static partial class Polyfill
     /// The default value is <see cref="CancellationToken.None"/>.
     /// </param>
     /// <returns>A task that represents the asynchronous write operation.</returns>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writelineasync#system-io-textwriter-writelineasync(system-readonlymemory((system-char))-system-threading-cancellationtoken)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writelineasync#system-io-textwriter-writelineasync(system-readonlymemory((system-char))-system-threading-cancellationtoken)
     public static ValueTask WriteLineAsync(
         this TextWriter target,
         ReadOnlyMemory<char> buffer,
@@ -355,7 +355,7 @@ static partial class Polyfill
     /// Writes a character span to the text stream.
     /// </summary>
     /// <param name="buffer">The character span to write.</param>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.write#system-io-textwriter-write(system-readonlyspan((system-char)))")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.write#system-io-textwriter-write(system-readonlyspan((system-char)))
     public static void Write(
         this TextWriter target,
         ReadOnlySpan<char> buffer)
@@ -378,7 +378,7 @@ static partial class Polyfill
     /// Writes the text representation of a character span to the text stream, followed by a line terminator.
     /// </summary>
     /// <param name="buffer">The char span value to write to the text stream.</param>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writeline#system-io-textwriter-writeline(system-readonlyspan((system-char)))")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.io.textwriter.writeline#system-io-textwriter-writeline(system-readonlyspan((system-char)))
     public static void WriteLine(
         this TextWriter target,
         ReadOnlySpan<char> buffer)

readme.md

@@ -478,7 +478,7 @@ The class `Polyfill` includes the following extension methods:
 
 #### ConcurrentBag<T>
 
- * `void Clear<T>(ConcurrentBag<T>)` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.collections.concurrent.concurrentbag-1.clear)
+ * `void Clear<T>()` [reference](https://learn.microsoft.com/en-us/dotnet/api/system.collections.concurrent.concurrentbag-1.clear)
 
 
 #### ConcurrentDictionary<TKey, TValue>

src/ApiBuilderTests/BuildApiTest.cs

@@ -1,3 +1,5 @@
+using Microsoft.CodeAnalysis;
+
 [TestFixture]
 class BuildApiTest
 {
@@ -204,16 +206,22 @@ static string BuildParameters(MethodDeclarationSyntax method)
 
     static bool TryGetReference(MethodDeclarationSyntax method, [NotNullWhen(true)] out string? reference)
     {
-        var descriptionAttribute = method.Attributes()
-            .SingleOrDefault(_ => _.Name.ToString() == "Link");
-        if (descriptionAttribute == null)
+        var syntaxTrivia = method.GetLeadingTrivia();
+        foreach (var trivia in syntaxTrivia)
         {
-            reference = null;
-            return false;
+            if (trivia.IsKind(SyntaxKind.SingleLineCommentTrivia))
+            {
+                var comment = trivia.ToString();
+                if (comment.StartsWith("//Link: "))
+                {
+                    reference = comment.Replace("//Link: ", string.Empty);
+                    return true;
+                }
+            }
         }
 
-        reference = descriptionAttribute.ArgumentList!.Arguments.Single().Value().Trim('"');
-        return true;
+        reference = null;
+        return false;
     }
 
 

src/Polyfill/CallerArgumentExpressionAttribute.cs

@@ -15,7 +15,7 @@ namespace System.Runtime.CompilerServices;
 [ExcludeFromCodeCoverage]
 [DebuggerNonUserCode]
 [AttributeUsage(AttributeTargets.Parameter)]
-[Link("https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.callerargumentexpressionattribute")]
+//Link: https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.callerargumentexpressionattribute
 #if PolyPublic
 public
 #endif

src/Polyfill/CollectionBuilderAttribute.cs

@@ -12,7 +12,7 @@ namespace System.Runtime.CompilerServices;
 [ExcludeFromCodeCoverage]
 [DebuggerNonUserCode]
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Interface, Inherited = false)]
-[Link("https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.collectionbuilderattribute")]
+//Link: https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.collectionbuilderattribute
 #if PolyPublic
 public
 #endif

src/Polyfill/CompilerFeatureRequiredAttribute.cs

@@ -18,7 +18,7 @@ namespace System.Runtime.CompilerServices;
     validOn: AttributeTargets.All,
     AllowMultiple = true,
     Inherited = false)]
-[Link("https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.compilerfeaturerequiredattribute")]
+//Link: https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.compilerfeaturerequiredattribute
 #if PolyPublic
 public
 #endif

src/Polyfill/ConstantExpectedAttribute.cs

@@ -18,7 +18,7 @@ namespace System.Diagnostics.CodeAnalysis;
 [ExcludeFromCodeCoverage]
 [DebuggerNonUserCode]
 [AttributeUsage(AttributeTargets.Parameter, Inherited = false)]
-[Link("https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.codeanalysis.constantexpectedattribute")]
+//Link: https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.codeanalysis.constantexpectedattribute
 #if PolyPublic
 public
 #endif

src/Polyfill/DateTimeOffsetPolyfill.cs

@@ -21,7 +21,7 @@ static class DateTimeOffsetPolyfill
     /// <summary>
     /// Tries to parse a string into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse#system-datetimeoffset-tryparse(system-string-system-iformatprovider-system-datetimeoffset@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse#system-datetimeoffset-tryparse(system-string-system-iformatprovider-system-datetimeoffset@)
     public static bool TryParse(string? target, IFormatProvider? provider, out DateTimeOffset result) =>
 #if NET7_0_OR_GREATER
         DateTimeOffset.TryParse(target, provider, out result);
@@ -34,7 +34,7 @@ public static bool TryParse(string? target, IFormatProvider? provider, out DateT
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse#system-datetimeoffset-tryparse(system-readonlyspan((system-char))-system-iformatprovider-system-datetimeoffset@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse#system-datetimeoffset-tryparse(system-readonlyspan((system-char))-system-iformatprovider-system-datetimeoffset@)
     public static bool TryParse(ReadOnlySpan<char> target, IFormatProvider? provider, out DateTimeOffset result) =>
 #if NET8_0_OR_GREATER
         DateTimeOffset.TryParse(target, provider, out result);
@@ -45,7 +45,7 @@ public static bool TryParse(ReadOnlySpan<char> target, IFormatProvider? provider
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse#system-datetimeoffset-tryparse(system-readonlyspan((system-char))-system-datetimeoffset@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse#system-datetimeoffset-tryparse(system-readonlyspan((system-char))-system-datetimeoffset@)
     public static bool TryParse(ReadOnlySpan<char> target, out DateTimeOffset result) =>
 #if NETSTANDARD2_1 || NETSTANDARD2_1_OR_GREATER || NET5_0_OR_GREATER
         DateTimeOffset.TryParse(target, out result);
@@ -56,7 +56,7 @@ public static bool TryParse(ReadOnlySpan<char> target, out DateTimeOffset result
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse#system-datetimeoffset-tryparse(system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetimeoffset@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparse#system-datetimeoffset-tryparse(system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetimeoffset@)
     public static bool TryParse(ReadOnlySpan<char> target, IFormatProvider? provider, DateTimeStyles styles, out DateTimeOffset result) =>
 #if NETSTANDARD2_1 || NETSTANDARD2_1_OR_GREATER || NET5_0_OR_GREATER
         DateTimeOffset.TryParse(target, provider, styles, out result);
@@ -67,7 +67,7 @@ public static bool TryParse(ReadOnlySpan<char> target, IFormatProvider? provider
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparseexact#system-datetimeoffset-tryparseexact(system-readonlyspan((system-char))-system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetimeoffset@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparseexact#system-datetimeoffset-tryparseexact(system-readonlyspan((system-char))-system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetimeoffset@)
     public static bool TryParseExact(ReadOnlySpan<char> target, string format, IFormatProvider? provider, DateTimeStyles styles, out DateTimeOffset result) =>
 #if NETSTANDARD2_1 || NETSTANDARD2_1_OR_GREATER || NET5_0_OR_GREATER
         DateTimeOffset.TryParseExact(target, format, provider, styles, out result);
@@ -78,7 +78,7 @@ public static bool TryParseExact(ReadOnlySpan<char> target, string format, IForm
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparseexact#system-datetimeoffset-tryparseexact(system-readonlyspan((system-char))-system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetimeoffset@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tryparseexact#system-datetimeoffset-tryparseexact(system-readonlyspan((system-char))-system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetimeoffset@)
     public static bool TryParseExact(ReadOnlySpan<char> target, ReadOnlySpan<char> format, IFormatProvider? provider, DateTimeStyles styles, out DateTimeOffset result) =>
 #if NETFRAMEWORK || NETSTANDARD2_0 || NETCOREAPP2_0
         DateTimeOffset.TryParseExact(target.ToString(), format.ToString(), provider, styles, out result);

src/Polyfill/DateTimePolyfill.cs

@@ -19,7 +19,7 @@ static class DateTimePolyfill
     /// <summary>
     /// Tries to parse a string into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparse#system-datetime-tryparse(system-string-system-iformatprovider-system-datetime@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparse#system-datetime-tryparse(system-string-system-iformatprovider-system-datetime@)
     public static bool TryParse(string? target, IFormatProvider? provider, out DateTime result) =>
 #if NET7_0_OR_GREATER
         DateTime.TryParse(target, provider, out result);
@@ -32,7 +32,7 @@ public static bool TryParse(string? target, IFormatProvider? provider, out DateT
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparse#system-datetime-tryparse(system-readonlyspan((system-char))-system-iformatprovider-system-datetime@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparse#system-datetime-tryparse(system-readonlyspan((system-char))-system-iformatprovider-system-datetime@)
     public static bool TryParse(ReadOnlySpan<char> target, IFormatProvider? provider, out DateTime result) =>
 #if NET8_0_OR_GREATER
         DateTime.TryParse(target, provider, out result);
@@ -43,7 +43,7 @@ public static bool TryParse(ReadOnlySpan<char> target, IFormatProvider? provider
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparse#system-datetime-tryparse(system-readonlyspan((system-char))-system-datetime@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparse#system-datetime-tryparse(system-readonlyspan((system-char))-system-datetime@)
     public static bool TryParse(ReadOnlySpan<char> target, out DateTime result) =>
 #if NETSTANDARD2_1 || NETSTANDARD2_1_OR_GREATER || NET5_0_OR_GREATER
         DateTime.TryParse(target, out result);
@@ -54,7 +54,7 @@ public static bool TryParse(ReadOnlySpan<char> target, out DateTime result) =>
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparse#system-datetime-tryparse(system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetime@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparse#system-datetime-tryparse(system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetime@)
     public static bool TryParse(ReadOnlySpan<char> target, IFormatProvider? provider, DateTimeStyles styles, out DateTime result) =>
 #if NETSTANDARD2_1 || NETSTANDARD2_1_OR_GREATER || NET5_0_OR_GREATER
         DateTime.TryParse(target, provider, styles, out result);
@@ -65,7 +65,7 @@ public static bool TryParse(ReadOnlySpan<char> target, IFormatProvider? provider
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparseexact#system-datetime-tryparseexact(system-readonlyspan((system-char))-system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetime@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparseexact#system-datetime-tryparseexact(system-readonlyspan((system-char))-system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetime@)
     public static bool TryParseExact(ReadOnlySpan<char> target, string format, IFormatProvider? provider, DateTimeStyles style, out DateTime result) =>
 #if NETSTANDARD2_1 || NETSTANDARD2_1_OR_GREATER || NET5_0_OR_GREATER
         DateTime.TryParseExact(target, format, provider, style, out result);
@@ -76,7 +76,7 @@ public static bool TryParseExact(ReadOnlySpan<char> target, string format, IForm
     /// <summary>
     /// Tries to parse a span of characters into a value.
     /// </summary>
-    [Link("https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparseexact#system-datetime-tryparseexact(system-readonlyspan((system-char))-system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetime@)")]
+    //Link: https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tryparseexact#system-datetime-tryparseexact(system-readonlyspan((system-char))-system-readonlyspan((system-char))-system-iformatprovider-system-globalization-datetimestyles-system-datetime@)
     public static bool TryParseExact(ReadOnlySpan<char> target, ReadOnlySpan<char> format, IFormatProvider? provider, DateTimeStyles styles, out DateTime result) =>
 #if NETFRAMEWORK || NETSTANDARD2_0 || NETCOREAPP2_0
         DateTime.TryParseExact(target.ToString(), format.ToString(), provider, styles, out result);

src/Polyfill/DisableRuntimeMarshallingAttribute.cs

@@ -29,7 +29,7 @@ namespace System.Runtime.CompilerServices;
 [ExcludeFromCodeCoverage]
 [DebuggerNonUserCode]
 [AttributeUsage(AttributeTargets.Assembly)]
-[Link("https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.disableruntimemarshallingattribute")]
+//Link: https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.disableruntimemarshallingattribute
 #if PolyPublic
 public
 #endif