If you’ve tried documenting .NETCF libraries which make use of Compact Framework specific types you’ll know that you have to do all sorts of workarounds and special builds to get an output which can successfully run through NDoc. This is because although the device specific assemblies such as Microsoft.WindowsCE.Forms are marked retargetable there isn’t an equivalent in the desktop framework to retarget to.
One solution is aggressive conditional compilation to hide all hints of of these device classes. Another way which is cleaner and easier to deal with when you are regularly updating code and documentation is to build your own dummy classes into your NDoc configuration of your project. I’ve done this for documenting my own code as I often find myself using MessageWindows etc in my projects. Ratherthan everyone re-invent the wheel you can use the file (see link below) as-is. You will still be producing a separate dll for documentation purposes but the amount of code you have to hack around with is greatly reduced.
Simply add the attached cs or vb file to your project. Then when you build the project in Debug or Release configuration absolutely nothing is added into your dll which will reference Microsoft.WindowsCE.Forms normally. But when you do an NDoc build and define the NDOC conditional constant it will magically spring into life and create a local dummy copy of the whole Microsoft.WindowsCE.Forms namespace. Because of the way the compiler chooses which class to reference your local version will take preference over the official library, thus removing all dependency on the Microsoft.WindowsCE.Forms library.
Microsoft.WindowsCE.Forms.zip (1.27 KB)
For this to work in VB there are a couple of additional points, firstly make sure you don’t have a Root Namespace configured (Project > Properties). You will also need VBCommenter to build the XML output used to feed Ndoc (Visual Studio 2005 will introduce built in XML comments generation for VB.NET projects).
Of course the same technique can be used for other device specific assemblies such as System.Data.SqlServerCe, although it contains a lot more types and so is less practical to do in this way. You can instead use this technique just with the individual types/methods you use…
3 replies on “NDoc helper for Microsoft.WindowsCE.Forms”
Where should the NDOC conditional constant be defined? When I define it in Microsoft.WindowsCE.Forms.cs, I get a compilation error.
Christine, You define the constant in your project properties. So for a project which has Debug and Release configurations already defined you create a new configuration – call it Documentation for example and in Project Properties > Build you can add NDOC to the list (DEBUG and TRACE are in there as standard)