diff --git a/ICSharpCode.NRefactory/Documentation/XmlDocumentationProvider.cs b/ICSharpCode.NRefactory/Documentation/XmlDocumentationProvider.cs
index 3301bf86e0..efaa539ceb 100644
--- a/ICSharpCode.NRefactory/Documentation/XmlDocumentationProvider.cs
+++ b/ICSharpCode.NRefactory/Documentation/XmlDocumentationProvider.cs
@@ -33,6 +33,8 @@ namespace ICSharpCode.NRefactory.Documentation
///
/// This class first creates an in-memory index of the .xml file, and then uses that to read only the requested members.
/// This way, we avoid keeping all the documentation in memory.
+ /// The .xml file is only opened when necessary, the file handle is not kept open all the time.
+ /// If the .xml file is changed, the index will automatically be recreated.
///
[Serializable]
public class XmlDocumentationProvider : IDocumentationProvider, IDeserializationCallback
diff --git a/ICSharpCode.NRefactory/ICSharpCode.NRefactory.csproj b/ICSharpCode.NRefactory/ICSharpCode.NRefactory.csproj
index adcd4b15e2..97e9772c33 100644
--- a/ICSharpCode.NRefactory/ICSharpCode.NRefactory.csproj
+++ b/ICSharpCode.NRefactory/ICSharpCode.NRefactory.csproj
@@ -229,5 +229,13 @@
Mono.Cecil
+
+
+ PatternMatching\Pattern Matching.html
+
+
+ Documentation\XML Documentation.html
+
+
\ No newline at end of file
diff --git a/README b/README
index 58ec8c97d8..5f54162681 100644
--- a/README
+++ b/README
@@ -42,9 +42,11 @@ ICSharpCode.NRefactory assembly
ICSharpCode.NRefactory.Documentation:
Classes for working with .xml documentation files.
+ See "doc/XML Documentation.html" for details.
ICSharpCode.NRefactory.PatternMatching:
Provides classes for pattern matching over the C# and VB ASTs.
+ See "doc/Pattern Matching.html" for details.
ICSharpCode.NRefactory.Util:
Various helper classes.
diff --git a/doc/TODO b/doc/TODO
index f0a970df52..047cdc1509 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -4,11 +4,13 @@ Parser:
- add API to report errors
- allow multithreaded parsing
+Type System:
+- Reduce memory usage
+- Interface Implementation Map
+
Resolver:
-- Tons of unit tests for TypeSystemConvertVisitor
- Port all #D resolver unit tests to NR
- Port all MD resolver unit tests to NR
-- Think about removing ParameterizedType and specializing the ITypeDefinition instead.
Features:
- Code Completion
diff --git a/doc/XML Documentation.html b/doc/XML Documentation.html
new file mode 100644
index 0000000000..c81b7e8fff
--- /dev/null
+++ b/doc/XML Documentation.html
@@ -0,0 +1,60 @@
+
+NRefactory - XML Documentation
+
+
NRefactory - XML Documentation
+
Providing documentation for the type system
+
+ When using CecilLoader, set the CecilLoader.DocumentationProvider
+ property to provide documentation for the loaded assemblies.
+ The XmlDocumentationProvider class is an IDocumentationProvider implementation
+ that can be used to read documentation from an external .xml file in the format generated by
+ Microsoft's C# compiler.
+
+
+ When parsing C# code, the TypeSystemConvertVisitor will load the documentation
+ from the XML comments by default. (this can be disabled using TODO).
+
+
+ Internally, the type system does not store XML documentation - instead, the documentation is
+ requested from the provider whenever the IEntity.Documentation
+ property is accessed.
+ For this purpose, the type system casts the parsed file to IUnresolvedDocumentationProvider
+ and tries to get the documentation.
+ This way, the CSharpParsedFile can provide the documentation from the XML comments.
+ If this fails, the type system casts the unresolved assembly/project content to IDocumentationProvider.
+ This is the way the request for documentation gets to the CecilLoader,
+ which in turn forwards it to the user-provided IDocumentationProvider.
+
+
cref
+
+ The syntax taken by the cref attribute depends on the documentation source.
+ For example, C# XML comments may use "List{T} if the appropriate using exists,
+ but .xml documentation files have to use the full ID string T:System.Collections.Generics.List`1.
+
+
+ For this reason, the IEntity.Documentation property returns a DocumentationComment
+ object that provides not only the XML text, but also a method that can be used to resolve cref
+ attributes.
+
+
+ Internally, the .xml file support uses the IDStringProvider;
+ whereas C# has its own small CSharpCrefParser.
+
+
XmlDocumentationProvider implementation notes
+
+ The XmlDocumentationProvider is designed to load large amounts
+ of documentation while using up only little memory.
+
+
+ When a new XmlDocumentationProvider is created, it will read the .xml file and
+ create a small in-memory index (using only 8 bytes per member).
+ When documentation is requested from the provider, it uses this index to find the correct
+ position in the .xml file, and parses only the interesting document fragment, not the whole file.
+
+
+ The XmlDocumentationProvider is serializable and will be included when serializing a Cecil-loaded
+ IUnresolvedAssembly. This way, an IDE like SharpDevelop can completely avoid parsing
+ the .xml documentation file when the user opens a solution (except for the first time).
+