Implemented review recommendations

Implements suggestions and recommendations suggested by the first review
of the "Advance C# linter based on mcs -t:module (#952)" pull request.

- Clarifies and simplifies description of linters and options
- Added links to help file and marked the mcsc linter as to be run only
  when file in buffer is saved or loaded.
- Added comments to the mcsc.vim file to clarify code
- removed type checks considered not necessary be reviewer.
- addresses findings by vader
- removed call to getcwd and cd in vim script
- handler expands file names relative to route of source tree into
  absolute pathes. Fixes errors not being marked when vim is started
  from subdirectory of source tree.
- implements tests for mcs.vim and mcsc.vim linter

1 files changed, 66 insertions, 39 deletions

diff --git a/doc/ale-cs.txt b/doc/ale-cs.txt
index 357d7387..eeb1abd1 100644
--- a/doc/ale-cs.txt
+++ b/doc/ale-cs.txt
@@ -3,10 +3,11 @@ ALE C# Integration                                             *ale-cs-options*
 
 
 ===============================================================================
-mcs                 																		           *ale-cs-mcs*
+mcs                                                                *ale-cs-mcs*
 
-  The mcs linter calls the mono mcs compiler setting the --parse and -unsafe
-  flags.
+  The mcs linter checks the syntax of the '*.cs' file loaded in the current
+  buffer only. It uses the --parse option of the mcs compiler and implicitly 
+  sets the -unsafe flag.
 
 g:ale_cs_mcs_options                                     *g:ale_cs_mcs_options*
                                                          *b:ale_cs_mcs_options*
@@ -14,62 +15,88 @@ g:ale_cs_mcs_options                                     *g:ale_cs_mcs_options*
   Type: String
   Default: `''`
 
-  This variable can be changed to modify flags given to mcs. The options
-  --parse and -unsafe are implicitly set.
+  This variable can be changed to pass additional flags given to mcs.
+
+  NOTE: The -unsafe flag is selected implicitly and thus does not need to be 
+  explicitly included in the |g:ale_cs_mcs_options| or |b:ale_cs_mcs_options|
+  parameter.
 
 
 ===============================================================================
 mcsc                                                              *ale-cs-mcsc*
 
-	The mcsc linter uses the mono mcs compiler to generate a temporary module
-  target file (-t:module) including all '*.cs' files contained in the
-	directory by specified by |g:ale_cs_mcsc_source| or |b:ale_cs_mcsc_source|
-  variable and all sub directories. Currently none can be excluded from
-  linting. It uses the assembly directories as specified by 
-	|g:ale_cs_mcsc_assembly_path| or |b:ale_cs_mcsc_assembly_path| and selects
-  the assembly files specified by |g:ale_cs_mcsc_assemblies| or 
-  |b:ale_cs_mcsc_assemblies|. The mcs -unsafe option is set implicitly and has
-  not to be added using |g:ale_cs_mcsc_options| or |b:ale_cs_mcsc_options|
-  variable.
-
-g:ale_cs_mcsc_options                                 *g:ale_cs_mcsc_options*
-                                                      *b:ale_cs_mcsc_options*
+  The mcsc linter uses the mono mcs compiler to generate a temporary module
+  target file (-t:module). The module includes including all '*.cs' files
+  contained in the directory tree rooted at the path defined by the 
+  |g:ale_cs_mcsc_source| or |b:ale_cs_mcsc_source| variable.
+  variable and all sub directories. 
+
+  The paths to search for additional assembly ('*.dll') files can be
+  specified using the |g:ale_cs_mcsc_assembly_path| or 
+  |b:ale_cs_mcsc_assembly_path| variable. The additional assembly files ('*.dll')
+  can be included through the |g:ale_cs_mcsc_assemblies| or 
+  |b:ale_cs_mcsc_assemblies| parameter. 
+
+  NOTE: mcs compiles sources in multiple phases. It stops compilation after
+  finding errors during the current phase.
+  For example assume a file named 'FileWithTypeError.cs' is edited and saved
+  which contains a Type error. In the same directory tree a file named
+  'FileWithSyntaxError.cs' exists which contains a syntax error 
+  (eg.: a missing '{'). 
+  In that case mcs and thus mcsc linter will stop after the syntax check phase is
+  finished and report the syntax error in the file 'FileWithSyntaxError.cs'. The
+  Type error in the file 'FileWithTypeError.cs is not seen jet.
+  The only possibility to find the error in in 'FileWithTypeError.cs' is to fix
+  the syntax error in 'FileWithSyntaxError.cs' first. After saving mcs will
+  successfully pass the syntax check phase and advance to the next compilation
+  phase at which the Type error hidden in 'FileWithTypeError.cs' is found  and 
+  now can be indicated  by ale.
+
+g:ale_cs_mcsc_options                                   *g:ale_cs_mcsc_options*
+                                                        *b:ale_cs_mcsc_options*
   Type: |String|
   Default: `''`
 
-  This variable can be set to set further options for example adding packages 
-  (eg.: -pkg:dotnet) with are not added per default.
+  This parameter can be used to define additional flags and parameters independent
+  of the source tree to be linted. The specified string is directly passed to
+  mcs compiler without any further change.
+
+  For example, to add the dotnet package which is not added per default
+
+      let g:ale_cs_mcs_options = '-pkg:dotnet'
 
-g:ale_cs_mcsc_source                                   *g:ale_cs_mcsc_source*
-                                                       *b:ale_cs_mcsc_source*
+  NOTE: The mcs -unsafe option is included implicitly per default. Therefore it
+  is not necessary to specify it explicitly through the |g:ale_cs_mcsc_options|
+  or |b:ale_cs_mcsc_options| parameter.
+
+g:ale_cs_mcsc_source                                     *g:ale_cs_mcsc_source*
+                                                         *b:ale_cs_mcsc_source*
   Type: |String|
   Default: `''`
 
-  This variable defines the base path of the directory tree the '*.cs' files
-  should be included into the compilation of the temporary module. If empty
-  the current directory is used.
+  This variable defines the root path of the directory tree searched for the
+  '*.cs' files to be linted. If empty the current working directory is used.
+
+  NOTE: Currently it is not possible to specify sub directories and
+  directory sub trees which shall not be searched for *.cs files.
 
-g:ale_cs_mcsc_assembly_path                     *g:ale_cs_mcsc_assembly_path*
-                                                *b:ale_cs_mcsc_assembly_path*
+g:ale_cs_mcsc_assembly_path                       *g:ale_cs_mcsc_assembly_path*
+                                                  *b:ale_cs_mcsc_assembly_path*
   Type: |List|
   Default: `[]`
 
-  This variable defines a list of absolute or relative path strings pointing
-  to the location of the assembly files (*.dll) to be considered by mcsc
-  linter. If the list is not empty the list will be added to the mcsc command
-  line using the -lib: flag of mcs.
+  This variable defines a list of path strings to be searched for external
+  assembly ('*.dll') files. The list is passed to the mcs compiler using the
+  '-lib:' flag. 
 
-g:ale_cs_mcsc_assemblies                            *g:ale_cs_mcsc_assemblies*
-                                                   *b:ale_cs_mcsc_assemblies*
+g:ale_cs_mcsc_assemblies                             *g:ale_cs_mcsc_assemblies*
+                                                     *b:ale_cs_mcsc_assemblies*
   Type: |List|
   Default: `[]`
 
-  This variable defines a list of assembly files (*.dll) to be considered by
-  the mono mcs compiler when generating the temporary module. If the list is
-  not empty the list of assemblies will be added to the mcsc command
-  line using the -r: flag of mcs. To change the search path mcs uses to 
-  locate the specified assembly files use |g:ale_cs_mcsc_assembly_path| or
-  |b:ale_cs_mcsc_assembly_path| variables
+  This variable defines a list of external assembly (*.dll) files required 
+  by the mono mcs compiler to generate a valid module target. The list is 
+  passed the mcs compiler using the '-r:' flag.
 
 ===============================================================================
   vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl: