Browse Source

Add documentation about XML documentation.

newNRvisualizers
Daniel Grunwald 14 years ago
parent
commit
bd9348d588
  1. 2
      ICSharpCode.NRefactory/Documentation/XmlDocumentationProvider.cs
  2. 8
      ICSharpCode.NRefactory/ICSharpCode.NRefactory.csproj
  3. 2
      README
  4. 6
      doc/TODO
  5. 60
      doc/XML Documentation.html

2
ICSharpCode.NRefactory/Documentation/XmlDocumentationProvider.cs

@ -33,6 +33,8 @@ namespace ICSharpCode.NRefactory.Documentation @@ -33,6 +33,8 @@ namespace ICSharpCode.NRefactory.Documentation
/// <remarks>
/// 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.
/// </remarks>
[Serializable]
public class XmlDocumentationProvider : IDocumentationProvider, IDeserializationCallback

8
ICSharpCode.NRefactory/ICSharpCode.NRefactory.csproj

@ -229,5 +229,13 @@ @@ -229,5 +229,13 @@
<Name>Mono.Cecil</Name>
</ProjectReference>
</ItemGroup>
<ItemGroup>
<None Include="..\doc\Pattern Matching.html">
<Link>PatternMatching\Pattern Matching.html</Link>
</None>
<None Include="..\doc\XML Documentation.html">
<Link>Documentation\XML Documentation.html</Link>
</None>
</ItemGroup>
<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
</Project>

2
README

@ -42,9 +42,11 @@ ICSharpCode.NRefactory assembly @@ -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.

6
doc/TODO

@ -4,11 +4,13 @@ Parser: @@ -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

60
doc/XML Documentation.html

@ -0,0 +1,60 @@ @@ -0,0 +1,60 @@
<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 <code>TODO</code>).
</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>CSharpParsedFile</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>
Loading…
Cancel
Save