From 6a70ccdc835125de87d8705851b2c97683873ce6 Mon Sep 17 00:00:00 2001
From: Siegfried Pammer <siegfriedpammer@gmail.com>
Date: Tue, 10 Jul 2018 08:52:04 +0200
Subject: [PATCH] Add documentation to the analyzer API.

---
 ILSpy/Analyzers/IAnalyzer.cs                  | 56 ++++++++++++++++++-
 ILSpy/Analyzers/ScopedWhereUsedAnalyzer.cs    |  2 -
 .../TreeNodes/AnalyzedMethodTreeNode.cs       |  4 --
 .../TreeNodes/AnalyzedTypeTreeNode.cs         |  1 -
 4 files changed, 54 insertions(+), 9 deletions(-)

diff --git a/ILSpy/Analyzers/IAnalyzer.cs b/ILSpy/Analyzers/IAnalyzer.cs
index 0b77a6513..9d052a761 100644
--- a/ILSpy/Analyzers/IAnalyzer.cs
+++ b/ILSpy/Analyzers/IAnalyzer.cs
@@ -20,9 +20,7 @@ using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Reflection.Metadata;
-using System.Text;
 using System.Threading;
-using System.Threading.Tasks;
 using ICSharpCode.Decompiler.TypeSystem;
 
 namespace ICSharpCode.ILSpy.Analyzers
@@ -33,25 +31,64 @@ namespace ICSharpCode.ILSpy.Analyzers
 	/// </summary>
 	public interface IAnalyzer<T> where T : IEntity
 	{
+		/// <summary>
+		/// The caption used in the analyzer tree view.
+		/// </summary>
 		string Text { get; }
+
+		/// <summary>
+		/// Returns true, if the analyzer should be shown for an entity, otherwise false.
+		/// </summary>
 		bool Show(T entity);
 	}
 
+	/// <summary>
+	/// This interface can be used to implement an analyzer that runs on a single entity.
+	/// For an example see <see cref="Builtin.MethodUsesAnalyzer"/>.
+	/// </summary>
+	/// <typeparam name="T">The type of enitities to be analyzed.</typeparam>
 	public interface IEntityAnalyzer<T> : IAnalyzer<T> where T : IEntity
 	{
+		/// <summary>
+		/// Returns all entities that the analyzer found in the given entity.
+		/// </summary>
 		IEnumerable<IEntity> Analyze(T analyzedEntity, AnalyzerContext context);
 	}
 
+	/// <summary>
+	/// This interface can be used to implement an analyzer that runs on multiple types.
+	/// </summary>
+	/// <typeparam name="T">The type of enitities to be analyzed.</typeparam>
 	public interface ITypeDefinitionAnalyzer<T> : IAnalyzer<T> where T : IEntity
 	{
+		/// <summary>
+		/// Returns all entities that the analyzer found in the given entity.
+		/// </summary>
+		/// <param name="analyzedEntity">The entity, which we are looking for.</param>
+		/// <param name="type">The type definition, we currently analyze.</param>
+		/// <param name="context">Context providing additional information.</param>
 		IEnumerable<IEntity> Analyze(T analyzedEntity, ITypeDefinition type, AnalyzerContext context);
 	}
 
+	/// <summary>
+	/// This interface can be used to implement an analyzer that runs on method bodies.
+	/// </summary>
+	/// <typeparam name="T">The type of enitities to be analyzed.</typeparam>
 	public interface IMethodBodyAnalyzer<T> : IAnalyzer<T> where T : IEntity
 	{
+		/// <summary>
+		/// Returns all entities that the analyzer found in the given method body.
+		/// </summary>
+		/// <param name="analyzedEntity">The entity, which we are looking for.</param>
+		/// <param name="method">The method we analyze.</param>
+		/// <param name="methodBody">The method body.</param>
+		/// <param name="context">Context providing additional information.</param>
 		IEnumerable<IEntity> Analyze(T analyzedEntity, IMethod method, MethodBodyBlock methodBody, AnalyzerContext context);
 	}
 
+	/// <summary>
+	/// Provides additional context for analyzers.
+	/// </summary>
 	public class AnalyzerContext
 	{
 		public AnalyzerContext(IDecompilerTypeSystem typeSystem)
@@ -59,9 +96,24 @@ namespace ICSharpCode.ILSpy.Analyzers
 			this.TypeSystem = typeSystem;
 		}
 
+		/// <summary>
+		/// A type system where all entities of the current assembly and its references can be found.
+		/// </summary>
 		public IDecompilerTypeSystem TypeSystem { get; }
+
+		/// <summary>
+		/// CancellationToken. Currently Analyzers do not support cancellation from the UI, but it should be checked nonetheless.
+		/// </summary>
 		public CancellationToken CancellationToken { get; internal set; }
+
+		/// <summary>
+		/// Mapping info to find parts of a method.
+		/// </summary>
 		public CodeMappingInfo CodeMappingInfo { get; internal set; }
+
+		/// <summary>
+		/// Currently used language.
+		/// </summary>
 		public Language Language { get; internal set; }
 	}
 }
diff --git a/ILSpy/Analyzers/ScopedWhereUsedAnalyzer.cs b/ILSpy/Analyzers/ScopedWhereUsedAnalyzer.cs
index acf5c1f64..7334171d2 100644
--- a/ILSpy/Analyzers/ScopedWhereUsedAnalyzer.cs
+++ b/ILSpy/Analyzers/ScopedWhereUsedAnalyzer.cs
@@ -19,14 +19,12 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Reflection;
 using System.Reflection.Metadata;
 using System.Threading;
 using ICSharpCode.Decompiler;
 using ICSharpCode.Decompiler.Metadata;
 using ICSharpCode.Decompiler.TypeSystem;
 using ICSharpCode.Decompiler.Util;
-using ICSharpCode.ILSpy.Analyzers;
 
 namespace ICSharpCode.ILSpy.Analyzers
 {
diff --git a/ILSpy/Analyzers/TreeNodes/AnalyzedMethodTreeNode.cs b/ILSpy/Analyzers/TreeNodes/AnalyzedMethodTreeNode.cs
index dad1f6cb7..71cb3f602 100644
--- a/ILSpy/Analyzers/TreeNodes/AnalyzedMethodTreeNode.cs
+++ b/ILSpy/Analyzers/TreeNodes/AnalyzedMethodTreeNode.cs
@@ -17,11 +17,7 @@
 // DEALINGS IN THE SOFTWARE.
 
 using System;
-using System.Reflection;
-using System.Reflection.Metadata;
-using ICSharpCode.Decompiler;
 using ICSharpCode.Decompiler.TypeSystem;
-using ICSharpCode.ILSpy.Analyzers;
 using ICSharpCode.ILSpy.TreeNodes;
 
 namespace ICSharpCode.ILSpy.Analyzers.TreeNodes
diff --git a/ILSpy/Analyzers/TreeNodes/AnalyzedTypeTreeNode.cs b/ILSpy/Analyzers/TreeNodes/AnalyzedTypeTreeNode.cs
index 21421e0db..46cd79e6f 100644
--- a/ILSpy/Analyzers/TreeNodes/AnalyzedTypeTreeNode.cs
+++ b/ILSpy/Analyzers/TreeNodes/AnalyzedTypeTreeNode.cs
@@ -18,7 +18,6 @@
 
 using System;
 using ICSharpCode.Decompiler.TypeSystem;
-using ICSharpCode.ILSpy.Analyzers;
 using ICSharpCode.ILSpy.TreeNodes;
 
 namespace ICSharpCode.ILSpy.Analyzers.TreeNodes