Merge pull request #2309 from mattwar/DocCommentId

Expose DocumentationCommentId as public API

src/Compilers/Core/Portable/CodeAnalysis.csproj

@@ -131,7 +131,7 @@
     <Compile Include="InternalImplementationOnlyAttribute.cs" />
     <Compile Include="InternalUtilities\AssemblyLocationLightUp.cs" />
     <Compile Include="Emit\EditAndContinueMethodDebugInformation.cs" />
-    <Compile Include="InternalUtilities\DocumentationCommentId.cs" />
+    <Compile Include="DocumentationCommentId.cs" />
     <Compile Include="Emit\EditAndContinue\SymbolMatcher.cs" />
     <Compile Include="InternalUtilities\FailFast.cs" />
     <Compile Include="InternalUtilities\FileStreamLightUp.cs" />

src/Compilers/Core/Portable/DiagnosticAnalyzer/SuppressMessageAttributeState.TargetSymbolResolver.cs

@@ -44,17 +44,12 @@ public TargetSymbolResolver(Compilation compilation, TargetScope scope, string f
 
             private static string RemovePrefix(string id, string prefix)
             {
-                if (prefix == null)
-                {
-                    return id;
-                }
-
-                if (id?.StartsWith(prefix, StringComparison.Ordinal) ?? false)
+                if (id != null && prefix != null && id.StartsWith(prefix, StringComparison.Ordinal))
                 {
                     return id.Substring(prefix.Length);
                 }
 
-                return null;
+                return id;
             }
 
             public void Resolve(IList<ISymbol> results)
@@ -65,8 +60,9 @@ public void Resolve(IList<ISymbol> results)
                 }
 
                 // Try to parse the name as declaration ID generated from symbol's documentation comment Id.
-                List<ISymbol> docIdResults;
-                if (DocumentationCommentId.TryGetSymbolsForDeclarationId(RemovePrefix(_name, s_suppressionPrefix), _compilation, out docIdResults))
+                var nameWithoutPrefix = RemovePrefix(_name, s_suppressionPrefix);
+                var docIdResults = DocumentationCommentId.GetSymbolsForDeclarationId(nameWithoutPrefix, _compilation);
+                if (docIdResults.Length > 0)
                 {
                     foreach (var result in docIdResults)
                     {

src/Compilers/Core/Portable/InternalUtilities/DocumentationCommentId.cs → src/Compilers/Core/Portable/DocumentationCommentId.cs

@@ -13,7 +13,7 @@ namespace Microsoft.CodeAnalysis
     /// <summary>
     /// APIs for constructing documentation comment id's, and finding symbols that match ids.
     /// </summary>
-    internal class DocumentationCommentId
+    public static class DocumentationCommentId
     {
         private class ListPool<T> : ObjectPool<List<T>>
         {
@@ -43,6 +43,11 @@ public new void Free(List<T> list)
         /// </summary>
         public static string CreateDeclarationId(ISymbol symbol)
         {
+            if (symbol == null)
+            {
+                throw new ArgumentNullException(nameof(symbol));
+            }
+
             var builder = new StringBuilder();
             var generator = new DeclarationGenerator(builder);
             generator.Visit(symbol);
@@ -55,6 +60,11 @@ public static string CreateDeclarationId(ISymbol symbol)
         /// </summary>
         public static string CreateReferenceId(ISymbol symbol)
         {
+            if (symbol == null)
+            {
+                throw new ArgumentNullException(nameof(symbol));
+            }
+
             if (symbol is INamespaceSymbol)
             {
                 return CreateDeclarationId(symbol);
@@ -69,19 +79,51 @@ public static string CreateReferenceId(ISymbol symbol)
         /// <summary>
         /// Gets all declaration symbols that match the declaration id string
         /// </summary>
-        public static IEnumerable<ISymbol> GetSymbolsForDeclarationId(string id, Compilation compilation)
+        public static ImmutableArray<ISymbol> GetSymbolsForDeclarationId(string id, Compilation compilation)
         {
-            List<ISymbol> results;
-            TryGetSymbolsForDeclarationId(id, compilation, out results);
-            return results;
+            if (id == null)
+            {
+                throw new ArgumentNullException(nameof(id));
+            }
+
+            if (compilation == null)
+            {
+                throw new ArgumentNullException(nameof(compilation));
+            }
+
+            var results = s_symbolListPool.Allocate();
+            try
+            {
+                Parser.ParseDeclaredSymbolId(id, compilation, results);
+                return results.ToImmutableArray();
+            }
+            finally
+            {
+                s_symbolListPool.ClearAndFree(results);
+            }
         }
 
         /// <summary>
-        /// Try get all declaration symbols that match the declaration id string
+        /// Try to get all the declaration symbols that match the declaration id string.
+        /// Returns true if atleast one symbol matches.
         /// </summary>
-        public static bool TryGetSymbolsForDeclarationId(string id, Compilation compilation, out List<ISymbol> results)
+        private static bool TryGetSymbolsForDeclarationId(string id, Compilation compilation, List<ISymbol> results)
         {
-            results = new List<ISymbol>();
+            if (id == null)
+            {
+                throw new ArgumentNullException(nameof(id));
+            }
+
+            if (compilation == null)
+            {
+                throw new ArgumentNullException(nameof(compilation));
+            }
+
+            if (results == null)
+            {
+                throw new ArgumentNullException(nameof(results));
+            }
+
             return Parser.ParseDeclaredSymbolId(id, compilation, results);
         }
 
@@ -90,6 +132,16 @@ public static bool TryGetSymbolsForDeclarationId(string id, Compilation compilat
         /// </summary>
         public static ISymbol GetFirstSymbolForDeclarationId(string id, Compilation compilation)
         {
+            if (id == null)
+            {
+                throw new ArgumentNullException(nameof(id));
+            }
+
+            if (compilation == null)
+            {
+                throw new ArgumentNullException(nameof(compilation));
+            }
+
             var results = s_symbolListPool.Allocate();
             try
             {
@@ -105,16 +157,57 @@ public static ISymbol GetFirstSymbolForDeclarationId(string id, Compilation comp
         /// <summary>
         /// Gets the symbols that match the reference id string.
         /// </summary>
-        public static IEnumerable<ISymbol> GetSymbolsForReferenceId(string id, Compilation compilation)
+        public static ImmutableArray<ISymbol> GetSymbolsForReferenceId(string id, Compilation compilation)
         {
+            if (id == null)
+            {
+                throw new ArgumentNullException(nameof(id));
+            }
+
+            if (compilation == null)
+            {
+                throw new ArgumentNullException(nameof(compilation));
+            }
+
+            var results = s_symbolListPool.Allocate();
+            try
+            {
+                TryGetSymbolsForReferenceId(id, compilation, results);
+                return results.ToImmutableArray();
+            }
+            finally
+            {
+                s_symbolListPool.ClearAndFree(results);
+            }
+        }
+
+        /// <summary>
+        /// Try to get all symbols that match the reference id string.
+        /// Returns true if atleast one symbol matches.
+        /// </summary>
+        private static bool TryGetSymbolsForReferenceId(string id, Compilation compilation, List<ISymbol> results)
+        {
+            if (id == null)
+            {
+                throw new ArgumentNullException(nameof(id));
+            }
+
+            if (compilation == null)
+            {
+                throw new ArgumentNullException(nameof(compilation));
+            }
+
+            if (results == null)
+            {
+                throw new ArgumentNullException(nameof(results));
+            }
+
             if (id.Length > 1 && id[0] == 'N' && id[1] == ':')
             {
-                return GetSymbolsForDeclarationId(id, compilation);
+                return TryGetSymbolsForDeclarationId(id, compilation, results);
             }
 
-            var results = new List<ISymbol>();
-            Parser.ParseReferencedSymbolId(id, compilation, results);
-            return results;
+            return Parser.ParseReferencedSymbolId(id, compilation, results);
         }
 
         /// <summary>
@@ -122,6 +215,16 @@ public static IEnumerable<ISymbol> GetSymbolsForReferenceId(string id, Compilati
         /// </summary>
         public static ISymbol GetFirstSymbolForReferenceId(string id, Compilation compilation)
         {
+            if (id == null)
+            {
+                throw new ArgumentNullException(nameof(id));
+            }
+
+            if (compilation == null)
+            {
+                throw new ArgumentNullException(nameof(compilation));
+            }
+
             if (id.Length > 1 && id[0] == 'N' && id[1] == ':')
             {
                 return GetFirstSymbolForDeclarationId(id, compilation);
@@ -524,15 +627,21 @@ public static bool ParseDeclaredSymbolId(string id, Compilation compilation, Lis
                 int index = 0;
                 results.Clear();
                 ParseDeclaredId(id, ref index, compilation, results);
-                return results.Count != 0;
+                return results.Count > 0;
             }
 
             // only supports type symbols
-            public static void ParseReferencedSymbolId(string id, Compilation compilation, List<ISymbol> results)
+            public static bool ParseReferencedSymbolId(string id, Compilation compilation, List<ISymbol> results)
             {
+                if (id == null)
+                {
+                    return false;
+                }
+
                 int index = 0;
                 results.Clear();
                 ParseTypeSymbol(id, ref index, compilation, null, results);
+                return results.Count > 0;
             }
 
             private static void ParseDeclaredId(string id, ref int index, Compilation compilation, List<ISymbol> results)

src/Compilers/Core/Portable/PublicAPI.txt

@@ -317,6 +317,7 @@ Microsoft.CodeAnalysis.DllImportData.ExactSpelling.get -> bool
 Microsoft.CodeAnalysis.DllImportData.ModuleName.get -> string
 Microsoft.CodeAnalysis.DllImportData.SetLastError.get -> bool
 Microsoft.CodeAnalysis.DllImportData.ThrowOnUnmappableCharacter.get -> bool?
+Microsoft.CodeAnalysis.DocumentationCommentId
 Microsoft.CodeAnalysis.DocumentationMode
 Microsoft.CodeAnalysis.DocumentationMode.Diagnose = 2 -> Microsoft.CodeAnalysis.DocumentationMode
 Microsoft.CodeAnalysis.DocumentationMode.None = 0 -> Microsoft.CodeAnalysis.DocumentationMode
@@ -1916,6 +1917,12 @@ static Microsoft.CodeAnalysis.Diagnostic.Create(string id, string category, Micr
 static Microsoft.CodeAnalysis.Diagnostics.CompilationWithAnalyzers.GetEffectiveDiagnostics(System.Collections.Generic.IEnumerable<Microsoft.CodeAnalysis.Diagnostic> diagnostics, Microsoft.CodeAnalysis.Compilation compilation) -> System.Collections.Generic.IEnumerable<Microsoft.CodeAnalysis.Diagnostic>
 static Microsoft.CodeAnalysis.Diagnostics.CompilationWithAnalyzers.IsDiagnosticAnalyzerSuppressed(Microsoft.CodeAnalysis.Diagnostics.DiagnosticAnalyzer analyzer, Microsoft.CodeAnalysis.CompilationOptions options, System.Action<System.Exception, Microsoft.CodeAnalysis.Diagnostics.DiagnosticAnalyzer, Microsoft.CodeAnalysis.Diagnostic> onAnalyzerException = null) -> bool
 static Microsoft.CodeAnalysis.Diagnostics.DiagnosticAnalyzerExtensions.WithAnalyzers(this Microsoft.CodeAnalysis.Compilation compilation, System.Collections.Immutable.ImmutableArray<Microsoft.CodeAnalysis.Diagnostics.DiagnosticAnalyzer> analyzers, Microsoft.CodeAnalysis.Diagnostics.AnalyzerOptions options = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> Microsoft.CodeAnalysis.Diagnostics.CompilationWithAnalyzers
+static Microsoft.CodeAnalysis.DocumentationCommentId.CreateDeclarationId(Microsoft.CodeAnalysis.ISymbol symbol) -> string
+static Microsoft.CodeAnalysis.DocumentationCommentId.CreateReferenceId(Microsoft.CodeAnalysis.ISymbol symbol) -> string
+static Microsoft.CodeAnalysis.DocumentationCommentId.GetFirstSymbolForDeclarationId(string id, Microsoft.CodeAnalysis.Compilation compilation) -> Microsoft.CodeAnalysis.ISymbol
+static Microsoft.CodeAnalysis.DocumentationCommentId.GetFirstSymbolForReferenceId(string id, Microsoft.CodeAnalysis.Compilation compilation) -> Microsoft.CodeAnalysis.ISymbol
+static Microsoft.CodeAnalysis.DocumentationCommentId.GetSymbolsForDeclarationId(string id, Microsoft.CodeAnalysis.Compilation compilation) -> System.Collections.Immutable.ImmutableArray<Microsoft.CodeAnalysis.ISymbol>
+static Microsoft.CodeAnalysis.DocumentationCommentId.GetSymbolsForReferenceId(string id, Microsoft.CodeAnalysis.Compilation compilation) -> System.Collections.Immutable.ImmutableArray<Microsoft.CodeAnalysis.ISymbol>
 static Microsoft.CodeAnalysis.Emit.EditAndContinueMethodDebugInformation.Create(System.Collections.Immutable.ImmutableArray<byte> compressedSlotMap, System.Collections.Immutable.ImmutableArray<byte> compressedLambdaMap) -> Microsoft.CodeAnalysis.Emit.EditAndContinueMethodDebugInformation
 static Microsoft.CodeAnalysis.Emit.EmitBaseline.CreateInitialBaseline(Microsoft.CodeAnalysis.ModuleMetadata module, System.Func<System.Reflection.Metadata.MethodDefinitionHandle, Microsoft.CodeAnalysis.Emit.EditAndContinueMethodDebugInformation> debugInformationProvider) -> Microsoft.CodeAnalysis.Emit.EmitBaseline
 static Microsoft.CodeAnalysis.Emit.EmitOptions.operator !=(Microsoft.CodeAnalysis.Emit.EmitOptions left, Microsoft.CodeAnalysis.Emit.EmitOptions right) -> bool

src/Workspaces/Core/Portable/Workspaces.csproj

@@ -76,9 +76,6 @@
     <Compile Include="..\..\..\Compilers\Core\Portable\InternalUtilities\DecimalUtilities.cs">
       <Link>InternalUtilities\DecimalUtilities.cs</Link>
     </Compile>
-    <Compile Include="..\..\..\Compilers\Core\Portable\InternalUtilities\DocumentationCommentId.cs">
-      <Link>InternalUtilities\DocumentationCommentId.cs</Link>
-    </Compile>
     <Compile Include="..\..\..\Compilers\Core\Portable\InternalUtilities\DocumentationCommentXmlNames.cs">
       <Link>InternalUtilities\DocumentationCommentXmlNames.cs</Link>
     </Compile>