Add documentation to methods for creating type references that describe the expected ITypeResolveContext for resolving those type references.

ICSharpCode.NRefactory.CSharp/Ast/AstType.cs

@@ -109,6 +109,9 @@ namespace ICSharpCode.NRefactory.CSharp
 		/// <summary>
 		/// Create an ITypeReference for this AstType.
 		/// </summary>
+		/// <remarks>
+		/// The resulting type reference requires a <see cref="CSharpTypeResolveContext"/> to be resolved.
+		/// </remarks>
 		public abstract ITypeReference ToTypeReference(SimpleNameLookupMode lookupMode = SimpleNameLookupMode.Type);
 		
 		/// <summary>

ICSharpCode.NRefactory.Tests/CSharp/Refactoring/TypeSystemAstBuilderTests.cs

@@ -72,7 +72,7 @@ namespace OtherNS {
 			baseClass = compilation.RootNamespace.GetTypeDefinition("Base", 1);
 			nestedClass = baseClass.NestedTypes.Single();
 			derivedClass = compilation.RootNamespace.GetTypeDefinition("Derived", 2);
-			systemClass = compilation.FindType("NS.System, MyAssembly").GetDefinition();
+			systemClass = compilation.RootNamespace.GetChildNamespace("NS").GetTypeDefinition("System", 0);
 		}
 		
 		TypeSystemAstBuilder CreateBuilder(ITypeDefinition currentTypeDef = null)
@@ -208,7 +208,7 @@ namespace OtherNS {
 		public void AmbiguousType()
 		{
 			Assert.AreEqual("System.Array", TypeToString(compilation.FindType(typeof(Array))));
-			Assert.AreEqual("OtherNS.Array", TypeToString(compilation.FindType("OtherNS.Array, MyAssembly")));
+			Assert.AreEqual("OtherNS.Array", TypeToString(compilation.MainAssembly.GetTypeDefinition("OtherNS", "Array", 0)));
 		}
 	}
 }

ICSharpCode.NRefactory/TypeSystem/ReflectionHelper.cs

@@ -48,6 +48,10 @@ namespace ICSharpCode.NRefactory.TypeSystem
 		/// Retrieves the specified type in this compilation.
 		/// Returns <see cref="SpecialType.UnknownType"/> if the type cannot be found in this compilation.
 		/// </summary>
+		/// <remarks>
+		/// This method cannot be used with open types; all type parameters will be substituted
+		/// with <see cref="SpecialType.UnknownType"/>.
+		/// </remarks>
 		public static IType FindType(this ICompilation compilation, Type type)
 		{
 			return type.ToTypeReference().Resolve(compilation.TypeResolveContext);
@@ -57,6 +61,8 @@ namespace ICSharpCode.NRefactory.TypeSystem
 		/// Retrieves the specified type in this compilation.
 		/// Returns <see cref="SpecialType.UnknownType"/> if the type cannot be found in this compilation.
 		/// </summary>
+		[Obsolete("Use ReflectionHelper.ParseReflectionName(reflectionTypeName).Resolve(compilation.TypeResolveContext) instead. " +
+		          "Make sure to read the ParseReflectionName() documentation for caveats.")]
 		public static IType FindType(this ICompilation compilation, string reflectionTypeName)
 		{
 			return ParseReflectionName(reflectionTypeName).Resolve(compilation.TypeResolveContext);
@@ -69,6 +75,12 @@ namespace ICSharpCode.NRefactory.TypeSystem
 		/// </summary>
 		/// <param name="type">The type to be converted.</param>
 		/// <returns>Returns the type reference.</returns>
+		/// <remarks>
+		/// If the type is open (contains type parameters '`0' or '``0'),
+		/// an <see cref="ITypeResolveContext"/> with the appropriate CurrentTypeDefinition/CurrentMember is required
+		/// to resolve the type reference.
+		/// For closed types, the root type resolve context for the compilation is sufficient.
+		/// </remarks>
 		public static ITypeReference ToTypeReference(this Type type)
 		{
 			if (type == null)
@@ -196,6 +208,15 @@ namespace ICSharpCode.NRefactory.TypeSystem
 		/// <param name="reflectionTypeName">The reflection name of the type.</param>
 		/// <exception cref="ReflectionNameParseException">The syntax of the reflection type name is invalid</exception>
 		/// <returns>A type reference that represents the reflection name.</returns>
+		/// <remarks>
+		/// If the type is open (contains type parameters '`0' or '``0'),
+		/// an <see cref="ITypeResolveContext"/> with the appropriate CurrentTypeDefinition/CurrentMember is required
+		/// to resolve the type reference.
+		/// For looking up closed, assembly qualified type names, the root type resolve context for the compilation
+		/// is sufficient.
+		/// When looking up a type name that isn't assembly qualified, the type reference only looks
+		/// in the <see cref="ITypeResolveContext.CurrentAssembly"/>.
+		/// </remarks>
 		public static ITypeReference ParseReflectionName(string reflectionTypeName)
 		{
 			if (reflectionTypeName == null)