You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
60 lines
3.0 KiB
60 lines
3.0 KiB
<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>
|
|
|