In part 1, I introduced a distributed programming environment called Global System Builder (GSB).  The IDE is an ASP.NET web application.  Another part of GSB is a Winforms application that runs on a remote computer that hosts an IronPython engine and communicates back to the web server using Windows Communication Foundation (WCF).  Hosted in the web browser is a source code editor with syntax highlighting and an interactive console – both of which communicate with the IronPython engine on the remote computer to execute Python code (and soon to be IronRuby using the DLR).

 

Also hosted in the web browser is a Virtual Earth control for locating remote computers, a Remote Desktop control to host a user session to the remote computer and a Smalltalk-like System or Class Browser for browsing classes (i.e. Types), member info, etc., that were loaded in the Winform app (i.e. GSB Service) on the remote computer.

 

 

 

One of the features I am implementing is the capability to extract code comments from any assembly that was loaded into the System Browser via the remote service (i.e. the Winforms application on the remote computer).  The idea is that as assemblies are loaded into the remote service, WCF communicates with the ASP.NET web server by passing up reflected assembly information (i.e. TypeInfo, MemberInfo, etc., using System.Reflection) that is then bound to a custom GridView control in the web browser, including code comments.

 

I implemented an ASP.NET AJAX hover menu that will display context sensitive menu items depending in which grid you are hovering over.  These menu items are helper functions (almost like macros) that will add the necessary IronPython (or IronRuby) code snippet to the console or code editor window, for example, to add an assembly references, stub out methods, insert DSL, etc.  For this post, I am discussing a way to view code comments that are part of an assembly, which when clicked in the hover menu, will display a panel with the code comment (plus parameter info, etc.) for the item hovered over, depending whether it is a type, method, prop, etc.  Think of it as a web-based version of Lutz Roeder’s cool Reflector, but in a Smalltalk like System Browser.

 

As an aside, I have one (major) design issue with the way assemblies are packaged out of Visual Studio as there is no way to include the code comments that you meticulously put in your source code files into the actual assembly itself.  It is packaged as a separate XML file.  In my mind, packaging the code comments in a separate file simply breaks the cardinal rule of encapsulation.  I wish Visual Studio at least gave you the option to embed your code comments directly into the assembly itself.

 

 

OK, so how to get at the code comments?  Searching through my vast libraries of reusable open source code on the internet, I came across this post and a nicely packaged class called XMLComments.  Only takes one line of code to implement and retrieve code comments. Perfect. Thanks Stephen Toub!

 

 

I used System.Windows.Forms.dll as the guinea pig as it is a whopping 5 megs in size and so is the companion XML code documentation file.  Everything seems to work ok, but a few observations.  It seems even in Microsoft’s own code documentation, only 50% of the +2200 Types in the assembly have a code comment.  Also, what about assemblies that don’t have the companion XML file and therefore no code comments at all?

 

There are a couple of choices, one is to extend the XMLComments class to derive some form of comments.  Ultimately, I would like to be able to build comments into the assembly (separate XML file or assembly) by using GSB’s source code editor and the necessary comments syntax to inject or attach comments to existing assemblies that don’t have code comments (loaded into the System Browser).

 

[Update August 14, 2007  I recently came across, “Documenting .NET Assemblies” by Robert Chartier (Thanks Robert!) that does a really nice and fast job of documenting assemblies that… have no documentation.  Exactly what I was looking for.  Robert has done a really nice job here, and has given me a few ideas to rework the System.Reflection code I already use to pull Assembly Names, Types, Member Info, etc.]

 

How important is this feature to the project?  Admittedly it is not a core feature, but at the same time, the point of the System Browser is to browse assemblies for reuse, or more importantly, for programming at a higher level of abstraction, so having code comments that came with the assembly or being able to attach your own code comments to the existing assembly, would be a good thing.  In my previous life in the electronics R&D industry, getting a component, like an IC, without the accompanying documentation with the package renders the component useless.  Looking at the Types list in the screenshot above, what do you think AmbientValueAttribute does?  Not sure what to make of our software development industry where source code documentation is either non-existent or in a form or place that is makes it virtually unusable.

 

Reusing assemblies to program at a higher level of abstraction is another topic and several posts in of itself.  There seems to be a lot of issues (angst?) in our industry about reusing other people’s source code or assemblies.  I do it all the time, both professionally (aka my day job) and in my little hobby here.  In fact the majority of GSB reuses several source code libraries and assemblies.  Without the many people that have taken the trouble to build the open source components that make up this application (aside from my own code), I would never be in the position I am today with a working application.

 

Anyway, I digress.  Displaying code comments is one feature of a growing list of features I collected after presenting GSB to a few potential users (i.e. dynamic programmers).  Based on the growing feature list, I still have a long way to go – not the 90% complete I alluded to in my previous post.  Also, I have decided to release GSB as open source when the DLR (with IronPython, IronRuby, Dynamic VB and Managed JScript) reaches RTM.  This is going to take a little bit of architectural refactoring (mostly the hosting namespace) to plug in the DLR engine and provide multi dynamic language support much like seen in this excellent video with