Edits to README.md

Author: cpsusie

DotNetVault/README.md

@@ -124,7 +124,13 @@ it upgrades to a writable lock and writes the value 0xDEAD_BEEF_CAFE_BABE_DEAD_B
 * Explaining how to debug the analyzer itself is beyond the scope of this document.  Essentially, one must use the *[vsix](https://github.com/cpsusie/DotNetVault/tree/v0.2.5.x/DotNetVault.Vsix)* project to launch a second special instance of visual studio that is running a debug build of the analyzers and has appropriate breakpoints set.  Then in the other instance, you can load the project that causes the issue you wish to debug.  This, obviously, is not for the faint-of-heart.  An important thing to note is that you **should not use the vsix extension project to install DotNetVault for normal use: analyzers imported via a vsix extension are incapable of causing compilation errors and this project depends heavily on compile-time analysis to ensure code is correct**.  To install DotNetVault for normal use, **use the nuget package**.    
   
 #### Guide To Using Large Value Types  
-In older versions of C\# we were cautioned against using large value types and value types with mutable state.  Recent changes to the C# language The ability to pass or return structs by reference or readonly reference and the *readonly* specifier (as applied to structs, struct properties, struct property get accessors and struct methods) work together to greatly mitigate prior concerns about the use of large structs.  Moreover, the readonly specifier allows specification of which methods and properties (if any) might mutate the value of a struct, making it easier to deal with mutable structs without defensive copying.  For isolating shared mutable state, however, particularly for use within a read-write or basic vault, large mutable value types are **ideal**.  For that reason, this project provides a [guide document](https://github.com/cpsusie/DotNetVault/blob/v0.2.5.x/Advantages%20of%20Using%20Large%20Mutable%20Structs.pdf) for how to design large immutable value types in general as well as how to design large mutable value types as a shared state repository for usage with a ReadWrite vault. If you have trouble reading the pdf with your browser or otherwise desire, the document can be downloaded [here](https://github.com/cpsusie/DotNetVault/raw/v0.2.5.x/Advantages%20of%20Using%20Large%20Mutable%20Structs.pdf).
+In older versions of C\# we were cautioned against using large value types and value types with mutable state.  Recent changes to the C# language greatly mitigate concerns about the use of large and/or mutable value types.  The ability to pass or return structs by reference and the  *readonly* specifier (as applied to things that hithertofore did not permit this specifier, shown below) work together to nearly eliminate prior problems.  The readonly specifier now can be applied:
+* To a struct itself to indicate the value is immutable and prevent defensive copying
+* To struct readonly properties (to indicate that the get accessor will not cause any mutations to the state of the struct as a side effect)
+* To struct read-write properties' get accessor (to indicate that the get accessor will not cause any mutations to the state of the struct as a side effect)
+* To struct methods, to indicate that the method will not cause side-effects that mutate the value of the struct.  
+
+Essentially, when we have an immutable or **mutable** value type that we accessing **through a readonly reference**, we can now force the compiler to omit defensive copying.  This is especially helpful when passing a mutable struct by readonly reference.  This facilitates both isolating shared mutable state and controlling read-only vs read-write accessibility.  Happily this ability works together with the *ReadWriteVault nearly **perfectly***. For that reason, this project provides a [guide document](https://github.com/cpsusie/DotNetVault/blob/v0.2.5.x/Advantages%20of%20Using%20Large%20Mutable%20Structs.pdf) for how to design large immutable value types in general as well as how to design large mutable value types as a shared state repository for usage with a ReadWrite vault. If you have trouble reading the pdf with your browser or otherwise desire, the document can be downloaded [here](https://github.com/cpsusie/DotNetVault/raw/v0.2.5.x/Advantages%20of%20Using%20Large%20Mutable%20Structs.pdf).
 
 ### **Development Roadmap** 
 

README.md

@@ -124,7 +124,13 @@ it upgrades to a writable lock and writes the value 0xDEAD_BEEF_CAFE_BABE_DEAD_B
 * Explaining how to debug the analyzer itself is beyond the scope of this document.  Essentially, one must use the *[vsix](https://github.com/cpsusie/DotNetVault/tree/v0.2.5.x/DotNetVault.Vsix)* project to launch a second special instance of visual studio that is running a debug build of the analyzers and has appropriate breakpoints set.  Then in the other instance, you can load the project that causes the issue you wish to debug.  This, obviously, is not for the faint-of-heart.  An important thing to note is that you **should not use the vsix extension project to install DotNetVault for normal use: analyzers imported via a vsix extension are incapable of causing compilation errors and this project depends heavily on compile-time analysis to ensure code is correct**.  To install DotNetVault for normal use, **use the nuget package**.    
   
 #### Guide To Using Large Value Types  
-In older versions of C\# we were cautioned against using large value types and value types with mutable state.  Recent changes to the C# language The ability to pass or return structs by reference or readonly reference and the *readonly* specifier (as applied to structs, struct properties, struct property get accessors and struct methods) work together to greatly mitigate prior concerns about the use of large structs.  Moreover, the readonly specifier allows specification of which methods and properties (if any) might mutate the value of a struct, making it easier to deal with mutable structs without defensive copying.  For isolating shared mutable state, however, particularly for use within a read-write or basic vault, large mutable value types are **ideal**.  For that reason, this project provides a [guide document](https://github.com/cpsusie/DotNetVault/blob/v0.2.5.x/Advantages%20of%20Using%20Large%20Mutable%20Structs.pdf) for how to design large immutable value types in general as well as how to design large mutable value types as a shared state repository for usage with a ReadWrite vault. If you have trouble reading the pdf with your browser or otherwise desire, the document can be downloaded [here](https://github.com/cpsusie/DotNetVault/raw/v0.2.5.x/Advantages%20of%20Using%20Large%20Mutable%20Structs.pdf).
+In older versions of C\# we were cautioned against using large value types and value types with mutable state.  Recent changes to the C# language greatly mitigate concerns about the use of large and/or mutable value types.  The ability to pass or return structs by reference and the  *readonly* specifier (as applied to things that hithertofore did not permit this specifier, shown below) work together to nearly eliminate prior problems.  The readonly specifier now can be applied:
+* To a struct itself to indicate the value is immutable and prevent defensive copying
+* To struct readonly properties (to indicate that the get accessor will not cause any mutations to the state of the struct as a side effect)
+* To struct read-write properties' get accessor (to indicate that the get accessor will not cause any mutations to the state of the struct as a side effect)
+* To struct methods, to indicate that the method will not cause side-effects that mutate the value of the struct.  
+
+Essentially, when we have an immutable or **mutable** value type that we accessing **through a readonly reference**, we can now force the compiler to omit defensive copying.  This is especially helpful when passing a mutable struct by readonly reference.  This facilitates both isolating shared mutable state and controlling read-only vs read-write accessibility.  Happily this ability works together with the *ReadWriteVault nearly **perfectly***. For that reason, this project provides a [guide document](https://github.com/cpsusie/DotNetVault/blob/v0.2.5.x/Advantages%20of%20Using%20Large%20Mutable%20Structs.pdf) for how to design large immutable value types in general as well as how to design large mutable value types as a shared state repository for usage with a ReadWrite vault. If you have trouble reading the pdf with your browser or otherwise desire, the document can be downloaded [here](https://github.com/cpsusie/DotNetVault/raw/v0.2.5.x/Advantages%20of%20Using%20Large%20Mutable%20Structs.pdf).
 
 ### **Development Roadmap**