Add a README and a TODO.

4 files changed, 132 insertions, 1 deletions

diff --git a/main/src/addins/MonoDevelop.AnalysisCore/MonoDevelop.AnalysisCore.addin.xml b/main/src/addins/MonoDevelop.AnalysisCore/MonoDevelop.AnalysisCore.addin.xml
index fdca1872e5..1dc2d86f7c 100644
--- a/main/src/addins/MonoDevelop.AnalysisCore/MonoDevelop.AnalysisCore.addin.xml
+++ b/main/src/addins/MonoDevelop.AnalysisCore/MonoDevelop.AnalysisCore.addin.xml
@@ -42,7 +42,7 @@
 	

 	<Extension path = "/MonoDevelop/AnalysisCore/Rules">

 		<Adaptor func="MonoDevelop.AnalysisCore.Adapters.GetCompilationUnit" input="ParsedDocument" output="CompilationUnit" />

-		<Category _name="Design Guidelines">

+		<Category _name="Design Guidelines" id="Design">

 			<Rule _name="Naming Conventions" func="MonoDevelop.AnalysisCore.Rules.NamingConventions" input="CompilationUnit" />

 		</Category>

 	</Extension>

diff --git a/main/src/addins/MonoDevelop.AnalysisCore/MonoDevelop.AnalysisCore.csproj b/main/src/addins/MonoDevelop.AnalysisCore/MonoDevelop.AnalysisCore.csproj
index 296c5b7eaa..15bc76a894 100644
--- a/main/src/addins/MonoDevelop.AnalysisCore/MonoDevelop.AnalysisCore.csproj
+++ b/main/src/addins/MonoDevelop.AnalysisCore/MonoDevelop.AnalysisCore.csproj
@@ -85,4 +85,8 @@
     <Compile Include="Adaptors.cs" />
   </ItemGroup>
   <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
+  <ItemGroup>
+    <None Include="README.txt" />
+    <None Include="TODO.txt" />
+  </ItemGroup>
 </Project>
\ No newline at end of file
diff --git a/main/src/addins/MonoDevelop.AnalysisCore/README.txt b/main/src/addins/MonoDevelop.AnalysisCore/README.txt
new file mode 100644
index 0000000000..5354297d9a
--- /dev/null
+++ b/main/src/addins/MonoDevelop.AnalysisCore/README.txt
@@ -0,0 +1,71 @@
+AnalysisCore currently provides several services -

+

+* The AnalysisService, a service for analyzing arbitrary input objects 

+  based on extensible rules.

+  

+* a TextEditorExtension that uses the AnalysisService to process the

+  editor's ParsedDocument when it's updated by the ProjectDomService,

+  and shows any resulting errors or warnings as underlines in the editor.

+

+== The AnalysisService ==

+

+AnalysisService is fundamentally based on the idea of an "Analyzer tree". 

+This is a tree where each node contains a "rule". Each rule is a Func<T,TRet>

+that transforms an input object to an output object. The tree is constructed 

+in such a way that the output type of each node's rule matches the input type 

+of its children, and leaf nodes always output IEnumerable<Result>. Thus, when

+Analyze (someInputObject) is called on the root node, the intermediates 

+objects propagate down the tree, and the Results are aggregated and returned.

+

+The trees are constructed based on rule nodes registered in the addin file. 

+Each node had an input and output "type", which is a string alias for a real 

+CLR type. Multiple aliases can be registered for one real type - the aliases 

+specify how the rule nodes can be connected, and the CLR types simply allow

+strongly typing the rule functions.

+

+== Extension Points ==

+

+The is an extension point "/MonoDevelop/AnalysisCore/Type" where type aliases 

+must be registered before use. Although aliases may only be registered once, 

+they may be used by any number of rules.

+

+There are two kinds of rule extension nodes, <Adaptor> and <Rule>. Both may be

+registered at the same extension point, "/MonoDevelop/AnalysisCore/Rules". 

+Both kinds of node must specify an input alias and a function name, which

+must correspond to a static method in the addin assembly. The static method's

+argument and return type must match the CLR types to which the input and 

+output aliases map.

+

+== Rules ==

+

+Rules always have an implicit output type of "Results", which is the built-in 

+alias for IEnumerable<Result>, and they also have a user-readable, localizable 

+name value, so that they may be displayed in UI for configuring which rules 

+are enabled.

+

+== Adaptors ==

+

+Adaptors must specify an output type, but are not user-visible so are not named.

+Their purpose is to do processing work that can be shared by multiple rules - 

+for example, an adaptor can generate a special type that is known to several 

+rules and includes additional preprocessing result, so that the rules so not 

+have to repeat the work. Adaptors may also be used to map input types to types 

+that are known by existing rules - for example, an adaptor could process the 

+output of the ASP.NET parser to prodice input known to existing C# rules.

+Adaptors may also be used to make branches conditional - if they output null, 

+then none of their children will be executed.

+

+When building the tree, the possible extension nodes used are filtered using

+optional filenames on the extension nodes. If an adaptor is filtered out, 

+then none of the nodes that consume its output can be used, so they need not 

+be filtered explicitly. For example, if there were an adaptor that cast an

+ICompilationUnit input to a CSharpCompilationUnit output, then it should be 

+filtered on the .cs file extension, and any rules with a CSharpCompilationUnit

+input would not be used.

+

+Adaptors can produce more than one output quite easily. If the outputs are

+a collection, then simply make the collection type the output type. If there

+are several different output objects, they can be aggregated on properties of

+a new type which can be used as the output type. Consumers may consume this

+type directly, or multiple additional adaptor rules may be used to pick off 

+the individual objects.
\ No newline at end of file
diff --git a/main/src/addins/MonoDevelop.AnalysisCore/TODO.txt b/main/src/addins/MonoDevelop.AnalysisCore/TODO.txt
new file mode 100644
index 0000000000..d4966d38d2
--- /dev/null
+++ b/main/src/addins/MonoDevelop.AnalysisCore/TODO.txt
@@ -0,0 +1,56 @@
+Some things that still need to be done in AnalyzerCore:

+

+* LOTS of rules - both generic .NET (for ICompilationUnit) and 

+  using an adaptor that would invoke the new C# parser.

+

+* A tooltip provider, for inspecting the error underlines.

+

+* A pad, for viewing the rules list more directly.

+

+* Options for diablign on-the-fly analysis

+

+* Support for configuring which rules are used, via additional 

+  filters when building the analysis tree.

+

+* A GUI for configuring the rules used.

+

+* Configurable rules. Rules should be able to specify a configuration 

+  object type in the addins file, and a GUI panel for editing the values.

+  A more specialized analysis tree nodes could be used for rules with

+  options, which would be Func<TIn,TOptions,TOut>

+

+* A scheduler for analysis jobs that would automatically discard outdated 

+  queued jobs when a newer job comes in.

+

+* Ability for results to include a "quick fix". This would be a command which 

+  would be shown in the menu context menu. Possibly this could be done by 

+  simply flagging results with a key to a handler in another extension point.

+

+* UserVisibleStringCollection type and a rule to spellcheck it, so anything

+  can output this node to generate spellchecking results.

+

+

+Some things that would be nice, but aren't so immediately important:

+

+* Profiling, both CPU and memory.

+

+* Parallelize the analysis trees - should be quite easy.

+

+* Clean up the type handling - use more specialized analysis tree nodes

+  to avoid the wrapper DynamicMethods and the casts they do.

+

+* Commands to suppress individual results, persisted in suppression files.

+

+* Analysis on demand, with a results list. This could easily process all files 

+  in a prject or sln.

+

+* Support for specifying rule priorities and using multiple analyser 

+  trees at different frequencies for one document, in order to run 

+  cheaper or more userful rules more frequently.

+  

+* Project-wide on the fly analysis.

+

+* Solution-wide on the fly analysis.

+

+* Rules to analyze project settings.

+