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 the SkipXmlDocumentation property).
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 CSharpUnresolvedFile 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.
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.
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).