first pass at annotating the source

Author: shiftkey

VisualStudio.gitignore

@@ -1,16 +1,18 @@
-## Ignore Visual Studio temporary files, build results, and
-## files generated by popular Visual Studio add-ons.
-
-# User-specific files
+# temporary files generated by Visual Studio specific to the local user
+# contains profile information and other metadata
+# remove: if no longer targeting Visual Studio 2013 or earlier
 *.suo
 *.user
 *.userosscache
 *.sln.docstates
-
-# User-specific files (MonoDevelop/Xamarin Studio)
+#
+# new location for Visual Studio 2015
+.vs/
+#
+# specific to MonoDevelop and Xamarin Studio
 *.userprefs
 
-# Build results
+# build output folders generated by Visual Studio
 [Dd]ebug/
 [Dd]ebugPublic/
 [Rr]elease/
@@ -22,24 +24,37 @@ bld/
 [Bb]in/
 [Oo]bj/
 
-# Visual Studio 2015 cache/options directory
-.vs/
-
-# MSTest test Results
+# MSTest
+# a test framework from Microsoft
+# remove: if you are not using the MSTest runner to run your tests
 [Tt]est[Rr]esult*/
 [Bb]uild[Ll]og.*
 
-# NUNIT
+# NUnit
+# an open source test framework for .NET
+# site: http://www.nunit.org/
+# remove: if you are not using the NUnit test runner to run your tests
 *.VisualState.xml
 TestResult.xml
 
-# Build Results of an ATL Project
+# ATL (Active Template Library) Project
+# remove: if you do not have an ATL project in your solution
 [Dd]ebugPS/
 [Rr]eleasePS/
 dlldata.c
 
 # DNX
+# summary: the environment for cross-platform .NET development
+# site: https://github.com/aspnet/dnx
+#
+# locks the package references for a project to specific versions
+# url: https://github.com/aspnet/Home/wiki/Lock-file
+# remove: if you would like to lock your dependencies to a specific version
+#         when committing and prevent package restore from selecting a
+#         more recent version
 project.lock.json
+#
+# build output
 artifacts/
 
 *_i.c
@@ -67,7 +82,10 @@ artifacts/
 *.svclog
 *.scc
 
-# Chutzpah Test files
+# Chutzpah
+# a JS unit testing framework for commit
+# site: https://github.com/mmanela/chutzpah
+# include-when: you use the Chutzpah test runner to run tests
 _Chutzpah*
 
 # Visual C++ cache files
@@ -78,23 +96,29 @@ ipch/
 *.sdf
 *.cachefile
 
-# Visual Studio profiler
+# temporary files generated by the Visual Studio profiling tools
+# remove-when: you are not using these features of Visual Studio
 *.psess
 *.vsp
 *.vspx
 
 # TFS 2012 Local Workspace
+# remove-when: you are not using TFVC in this repository
 $tf/
 
 # Guidance Automation Toolkit
 *.gpState
 
-# ReSharper is a .NET coding add-in
+# ReSharper
+# a Visual Studio extension which supports various project types
+# site: https://www.jetbrains.com/resharper/
 _ReSharper*/
 *.[Rr]e[Ss]harper
 *.DotSettings.user
 
-# JustCode is a .NET coding add-in
+# JustCode
+# a Visual Studio extension for various project types
+# site: https://www.jetbrains.com/resharper/
 .JustCode
 
 # TeamCity is a build add-in
@@ -104,15 +128,19 @@ _TeamCity*
 *.dotCover
 
 # NCrunch
+# a continuous test runner for Visual Studio
+# site: TODO
 _NCrunch_*
 .*crunch*.local.xml
 nCrunchTemp_*
 
 # MightyMoose
+# site: TODO:
 *.mm.*
 AutoTest.Net/
 
-# Web workbench (sass)
+# Web Workbench
+# site: TODO:
 .sass-cache/
 
 # Installshield output folder
@@ -129,19 +157,25 @@ DocProject/Help/Html2
 DocProject/Help/html
 
 # Click-Once directory
+# remove:
 publish/
 
 # Publish Web Output
 *.[Pp]ublish.xml
 *.azurePubxml
-# TODO: Comment the next line if you want to checkin your web deploy settings 
+# TODO: Comment the next line if you want to checkin your web deploy settings
 # but database connection strings (with potential passwords) will be unencrypted
 *.pubxml
 *.publishproj
 
-# NuGet Packages
+# NuGet
+# summary: the package manager tool used in Visual Studio
+# url: https://nuget.org
+#
+# output packages created by NuGet
 *.nupkg
 # The packages folder can be ignored because of Package Restore
+# remove-if: you want to disable Package Restore
 **/packages/*
 # except build/, which is used as an MSBuild target.
 !**/packages/build/