TeXcomments

TeXcomments is an extension to Visual Studio that enables you to comment mathematical code using TeX (http://en.wikipedia.org/wiki/TeX).  The math mode in TeX converts text containing intuitive and efficent escape codes into sophisticated typeset mathematical equations.  TeXcomments uses jsMath (http://www.math.union.edu/~dpvc/jsmath/), an excellent implementation in javascript which typesets math mode TeX in web pages using real fonts rather than bitmaps. 

When TeXcomments is installed, hovering the mouse over an xml comment region of source code that includes math mode TeX will open a window previewing the comment with typeset mathematics.  The same 'stay on top' window is used for all comments, in C# or VB.NET, so moving the mouse from comment region to comment region will change what is displayed in the window.

As .NET becomes more math friendly with the introduction of F#, the Numerics namespace, and functional programming, it will become more important to document complex algorithms using real equations entered directly in the source code comments.  TeXcomments is only the beginning of a complete documentation system incorporating typeset math.

Possible future additions:

Unfortunately I haven't found a way to extend (although I may have missed it) the object browser to have the TeX comments typeset in the bottom right window.  This would be an ideal place to show these, so users could read the typeset math without requiring the source code.

It also seems possible to extend Sandcastle so the TeX comments would show up in official documentation as well.  I would be grateful to any expert in extending Sandcastle to implement this feature.

Installation:

jsMath needs to be installed to make TeXcomments work.

1. Go to the jsMath download page (http://sourceforge.net/projects/jsmath/files/) and get the latest jsMath code.
2. Unzip jsMath to C:\  
3. open the file C:\jsMath\easy\load.js in notepad and change line 34 from
     root: "",
      to
     root: "file:///c:/jsMath/",
4. I also recommend changing processSingleDollars to 1
5. Install the fonts (http://www.math.union.edu/~dpvc/jsmath/download/jsMath-fonts.html).  The Bakoma fonts work well with ClearType.
6. Install the TeXcomments extension from this site.
7. Try it out: enter the following example in a <remarks> section of an xml comment and then hover your mouse.
       ''' <remarks>Solves for the roots of the quadratic $ax^2 + bx + c=0$ as
       ''' $$ x = {{-b \pm \sqrt{b^2-4ac}} \over 2a} $$
       ''' </remarks>
8. the first time the window pops up a message might appear saying to activate scripts.  Click OK.  You only need to do this once. (I couldn't figure out how to enable scripts programmatically in the WebBrowser control)

Have fun!

Notes:

1. Clicking on the help button opens a cheat sheet with most of the TeX escape codes.  See the jsMath website for more information.
2. Since xml doesn't allow amperstands alone, when the amperstand appears in TeX it needs to be replaced by &amp; for added clarity, TexComments replaces \# by &amp;
   ie. $$ \pmatrix{a & b \cr g & h} $$ has to be written $$ \pmatrix{a \# b \cr g \# h} $$