# 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 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 `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).