For those of you who many be asking what is he talking about, Inline XML comments in your source?  Well, that would be (in C#) all those /// comments you see from time to time in source code like so.

namespace TestNamespace
{
/// <summary> 
///    Tests whether sandcastle can handle all c# tags as defined at 
///    http://msdn2.microsoft.com/en-us/library/5ast78ax.aspx. 
///    Comments of method "Increment (int step)" include almost all tags. 
///    Method "Swap" is used to test generics tags, such as "typeparam". 
///    <threadsafety static="true" instance="false"/> 
/// </summary> 
[Serializable()]
public class StoredNumber
{  

/// <summary> 
///    Initializes the stored number class with a starting value. 
/// </summary> 
public StoredNumber( int value )
{ number = value; }

However today, I have noticed that many open source projects and a good share of commercial applications do not bother marking up their source code with XML comments. Maybe one contributing factor is that nDoc died, ok you can still download version 1.3 but it is over two years old now and Microsoft’s answer to this solution Sandcastle is not quite as snazzy as nDoc was i.e. Command-line interface, or maybe propel are just not aware of their options. 

The following information outlines what you need to install so you can create proper Inline API (MSDN-style) documentation.  Here is a list of programs you need to install.

Sandcastle:

Microsoft home page for Sandcastle

You can download it from CodePlex http://www.codeplex.com/Sandcastle

Sandcastle, created by Microsoft, is a free tool used for creating MSDN-style documentation from .NET assemblies and their associated XML comment files. It is command-line based and has no GUI front-end, project management features, or an automated build process

SHFB (Sandcastle Help File Builder):

You can download SHFB from CodePlex http://www.codeplex.com/SHFB

SHFB is a GUI interface that almost looks identical to the NDoc interface so anyone familiar with NDoc should be quite comfortable using it.  It uses the underlining Sandcastle API to generate an HTML 1.x (.CHM) file, an HTML 2.x (.HxS) file, and/or a web site.

SHFB Requirements

In order to use SHFB you will need the following:

- The .NET 2.0 Framework

- The latest version of Sandcastle. 
- The HTML Help Workshop for building HTML Help 1.x (.CHM) help files

- The HTML 2.x compiler for building HTML Help 2.x (.HxS) help files

You can obtain the HTML builders by installing the Visual Studio 2008 SDK these are the latest builds.

XML Documentation Comments Guide:

Home page http://www.dynicity.com/downloads/default.aspx

Download the “Windows Installer” at http://www.dynicity.com/downloads/XMLDocCommentsGuide.exe

This is a help file with a very nice collection of information on how to use XML Comment tags properly in your source code, it has lots of links to some good tutorials and examples. 

DocProject for 2008:

Home page from CodePlex for DocProject

DocProject drives the Sandcastle help generation tools using the power of Visual Studio 2005/2008 and MSBuild. Choose from various project templates that build compiled help version 1.x or 2.x for all project references. DocProject facilitates the administration and development of project documentation with Sandcastle, allowing you to use the integrated tools of Visual Studio to customize Sandcastle’s output.

Example Links:

.NET Documentation Guidelines (version 2.5)

http://p3net.mvps.org/downloads/docs/DocGuidelines.doc 

XML Documentation in C# (Anson Horton, C# Compiler Program Manager)

http://cyrino.members.winisp.net/9112006/XMLDocs.doc

C# XML Documentation (Alan Dean)

http://thoughtpad.net/alan-dean/cs-xml-documentation.html

C# and XML Source Code Documentation

Documenting C# source code with XML Comments

Her owner has spent several days throwing together an InfoPath application for his employer and is quite happy with his work. Butters thinks that he should be ashamed because he is paid to be an “architect” and he has built an application his mother could probably get going in a pinch.

“But, Butters,” his owner exclaimed, “the point is to use the right tool for the job. I am just making a little form that business folks fill out and use to save XML documents. This is exactly what InfoPath is for, and it is so gosh, darned easy.”

“Oh,” replies Butters, “and I suppose there is validation logic and conditional formatting and other event automation going on in the form?”

“Uh, yes. Aren’t you a dog?”

“And I suppose all of those things are written right into the view, which is data bound directly onto the data sources?”

“Well, yeah. Aren’t bulldogs supposed to be one of the dumber breeds?”

“And didn’t you just blog about how easy the new MVC framework from Microsoft will make these things? Do you not promote yourself as one who can spin that code as quickly as clicking your way through the stupid InfoPath designer?”

“Yeah, I know, Butters. I am feeling kind of guilty about this.”

“You should, InfoPath Boy. You have all these great theories about separation of concerns, thin UI, and data abstraction, yet you solve a coding problem with InfoPath? You, sir, are not worthy of your peers.”

“Damn you, Butters. Damn you,” I replied.

“Standards? Why Bother?” asked Bill.

XForms is a way of expressing data and business logic into an XML instance that you can embed into an XHTML file and run in your favorite browser (sort of). XForms essentially provides a complete MVC programming model complete with events and view binding available within an XML file. Wikipedia describes XForms thusly:

XForms is an XML format for the specification of a data processing model for XML data and user interface(s) for the XML data, such as web forms. XForms was designed to be the next generation of HTML / XHTML forms, but is generic enough that it can also be used in a standalone manner or with presentation languages other than XHTML to describe a user interface and a set of common data manipulation tasks.

Of course, an XML instance cannot do anything by itself, it merely represents potential for action. In order to execute the business logic and view represented in an XForm you need an XForm execution engine. Significant XForms engines fall into 2 camps, each with their own set of vendors and advocates. The different strategies are browser execution and server execution.

Browser Execution Engines

FireFox leads off with native support baked into the browser. This makes a convenient platform for a closed ecosystem like an enterprise document workflow application.

Additionally, plugins are available for IE and other browsers. The leading plugin for IE comes from formsPlayer, although Pico Forms is hot on their trail with a plugin in its 3rd beta.  Pico Forms also has a custom XHTML browser and promotes XForms in the mobile space.

Lastly, two XForms Engine implementations exist (that I know of) in the form of JavaScript libraries.

The first is from the open source project FormFaces and has not seen active development since January of 2007. FormFaces implemetns much of the XForms specifications and as long as your application doesn’t need sliders to do range selections, this is viable option. The second is a forthcoming product from the plugin provider, formsPlayer. In exchanges with the CEO of formsPlayer I learned their implementation is close to done. I actually am hoping to see a demo next week.

These JS libraries provide the most realistic option for getting your XForm application to function on the web as no thick app requirements exist on the client.

In order to get the XForms to do something interesting, it is likely you will need to include some other dynamic content technology into your application. I have had some success in including the Yahoo UI AJAX library and triggering the AJAX controls using the data model event handlers. A model of this implementation is illustrated below.

Click the image for a larger version.

Server Side Engines

The idea here is that XForms are parsed and rendered into HTML on the server and subsequent changes to the embedded data model are managed by round tripping to the server. Sure this works, but it kind of takes all the fun out of it.

IBM is a major player here as well as a company called Orbeon and even Adobe has skin in the game.

Now What?

On November 29th, the W3C working group for XForms promoted XForms 1.1 specification to Release Candidate stage. This is really good news for vendors and developers embracing XForms technology because it represents a commitment to the technology by several leading adopters.

Although this technology is in its infancy, I strongly encourage you to take a look at it the next time you are asked to implement a dynamic forms application within your enterprise. After all, how many times must we reinvent this wheel?

For More Information

Some links I have found very useful in learning more about XForms are below:

• The W3C XForms Working Group
• XForms Tutorial
• XForms Institute

Technorati Tags: XForms,XML