Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: 810a1e8911
Fetching contributors…

Cannot retrieve contributors at this time

61 lines (60 sloc) 3.099 kB
<html>
<head><title>NRefactory - XML Documentation</title></head>
<body>
<h1>NRefactory - XML Documentation</h1>
<h2>Providing documentation for the type system</h2>
<p>
When using CecilLoader, set the <code>CecilLoader.DocumentationProvider</code>
property to provide documentation for the loaded assemblies.
The <code>XmlDocumentationProvider</code> class is an <code>IDocumentationProvider</code> implementation
that can be used to read documentation from an external .xml file in the format generated by
Microsoft's C# compiler.
</p>
<p>
When parsing C# code, the <code>TypeSystemConvertVisitor</code> will load the documentation
from the XML comments by default. (this can be disabled using the <code>SkipXmlDocumentation</code> property).
</p>
<p>
Internally, the type system does not store XML documentation - instead, the documentation is
requested from the provider whenever the <code>IEntity.Documentation</code>
property is accessed.<br/>
For this purpose, the type system casts the parsed file to <code>IUnresolvedDocumentationProvider</code>
and tries to get the documentation.
This way, the <code>CSharpUnresolvedFile</code> can provide the documentation from the XML comments.<br/>
If this fails, the type system casts the unresolved assembly/project content to <code>IDocumentationProvider</code>.
This is the way the request for documentation gets to the <code>CecilLoader</code>,
which in turn forwards it to the user-provided <code>IDocumentationProvider</code>.
</p>
<h2>cref</h2>
<p>
The syntax taken by the <code>cref</code> attribute depends on the documentation source.
For example, C# XML comments may use "<code>List{T}</code> if the appropriate <code>using</code> exists,
but .xml documentation files have to use the full ID string <code>T:System.Collections.Generics.List`1</code>.
</p>
<p>
For this reason, the <code>IEntity.Documentation</code> property returns a <code>DocumentationComment</code>
object that provides not only the XML text, but also a method that can be used to resolve <code>cref</code>
attributes.
</p>
<p>
Internally, the .xml file support uses the <code>IDStringProvider</code>;
whereas C# has its own small <code>CSharpCrefParser</code>.
</p>
<h2>XmlDocumentationProvider implementation notes</h2>
<p>
The <code>XmlDocumentationProvider</code> is designed to load large amounts
of documentation while using up only little memory.
</p>
<p>
When a new <code>XmlDocumentationProvider</code> 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.
</p>
<p>
The <code>XmlDocumentationProvider</code> is serializable and will be included when serializing a Cecil-loaded
<code>IUnresolvedAssembly</code>. 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).
</p>
</body>
</html>
Jump to Line
Something went wrong with that request. Please try again.