Interesting article about a couple of lesser known features of XML doc comments - multi-line comments and easier support for referencing generics.

I’ve finally taken some time and looked at Sandcastle, the new Microsoft alternative to API documentation rendering. Now that I’ve used it, I’ve decided that either Microsoft is jumping the gun on releasing this thing as any nature of “Community Technology Preview” or Microsoft just generally hates people who need to compile documentation.

“But why,” you might ask, “would you say something like that?”

You, the asker of such a question, have obviously not used Microsoft help compilers.

First Microsoft gave us HTML Help Workshop. If you haven’t used HTML Help Workshop, save yourself the trouble. It sucks. It’s the epitome of late 90’s UI design that basically gives you no indication of what to do or how to do it. RTFM, you loser. You are not smart enough to start up HTML Help Workshop and go.

But HTML Help Workshop is what we’ve got and that’s about where it stayed. It comes with the HTML Help Compiler, which basically crunches all of your HTML help documents into one file that can be distributed - a CHM file. The HTML Help Compiler is actually the important part of the workshop package and is generally the only piece that any normal human can take advantage of.

The problem then becomes figuring out what all the pieces are to get the compiler to run. You’ve got your project file, your index file, your table of contents file, your HTML files that actually contain the body of your help… it’s clunky.

Enter products like RoboHelp that make the process simpler for the standard documentation person. Docs get written, the clunkiness of the process gets abstracted away, and out the back end comes the CHM. Magic! The world forgets about HTML Help Workshop and uses products that work.

Fast forward a bit and along comes along .NET, with its fancy inline XML documentation comments. A stroke of genius, really - you can write your API doc along with the code it corresponds to and automatically create an XML document with that API documentation that can be transformed however you like.

For a very short period of time (relatively speaking), we were back to clunky, but before you know it, lickety-split, we have NDoc rescuing us. Not only that, but NDoc extends on the basic set of XML tags (sort of the way Netscape and IE “extended” HTML and ended up helping to shape the standard) to encompass common elements that get documented.

Anyone who is anyone uses NDoc. Seriously. We all use it, we all love it, it’s the de facto standard for generated API documentation. The really cool thing is that not only is it simple to use by itself, but it’s integrated into NAnt, so it can be automated in the build. It’s The Way and The Light.

So we’re in the Age of Not Clunky and chugging along great…

…until Microsoft trots up and chucks this… thing… out there called “Sandcastle” that they apparently use to render their own internal documentation. The community seems to want to latch onto this thing, but the truth of the matter is: it sucks. And you know why? We’re back to clunky. It’s just as difficult to use as HTML Help Workshop. Microsoft hasn’t made a single step forward on the path to easy help generation, they just keep throwing half-baked tools at it.

For the record, I’m using the August 2006 CTP of Sandcastle as the basis for my statements. I’ve got some test classes that I have for CR_Documentor that I use to see if CR_Documentor renders the preview the way NDoc does. Today I got the Sandcastle docs building for my test classes so I could get started on the Sandcastle renderer in CR_Documentor.

Holy crap.

I mean, seriously.

First, it takes 12 steps to render a CHM out of Sandcastle, each step involving running a different command-line tool to transform this XML into that XML or compile this HTML into that CHM or whatever. In fact, the last line is a call to the HTML Help Compiler previously mentioned, so don’t forget to have that installed.

Okay, so that’s not horrible, and it can be automated, but one would think that the automation scripts would be part of the CTP. Unfortunately, not so much. The community has rallied and there are now upwards of ten different GUIs and scripts and tools to automate this thing, most of which will become obsolete when (if) we get something decent out of the Sandcastle team.

Let’s ignore the bajillion step process for a moment, though. Let’s instead look at the documentation they provided to help us get going and… what? What’s that you say? No documentation provided?

That’s awesome.

Okay, so bajillion-step-process and distinct-lack-of-any-sort-of-formal-documentation aside, what’s really eating me here is the lack of out-of-the-box support for tags we NDoc users all sort of consider standard. For example, the <see langword="null" /> sorts of things that are strewn throughout documentation but are blatantly missing from Sandcastle.

I found a forum on this very issue and the recommendation from the Sandcastle team thus far is to modify the “main_sandcastle.xsl” file to add custom support for the tags.

Commonly used tags as a “custom extension” is a patently unacceptable solution. It’s sort of like someone saying, “Yeah, we just came out with this new VCR, but only tapes from Maxell will play in it. In some cases you’ll luck out, but in most cases you will probably have to do some extra work to fix the VCR so it’ll play the rest of your tapes.”

I’ve posted to the forum that I think they should support more out-of-the-box tags rather than sticking to the small subset that appear in the MSDN documentation. We’ll see what comes of it. Right now I can’t even get all of the standard tags to render right. For example, good luck getting a <list /> to render (which is one of the tags they actually list in the MSDN documentation as supported). I sure haven’t succeeded. Sort of puts a damper on the CR_Documentor emulation since I have no idea where they’re actually going to end up.

I guess I’m just irritated that such a big stir has been made over this thing and it’s not all that great. I can write a set of utilities to do something and make it super cumbersome and not support common stuff, too, but somehow I don’t think I’m going to get the level of community adoption we’re seeing here. It’s like they released an alpha level product and they maybe should have waited until it was at least beta before issuing a preview.

Maybe they should have a comprehensive list of what’s done and what they plan to do and let us all see that so we can go, “Oh, hey, they might not support such-and-such now, but they will soon” or, “They think this feature’s done, but it sure doesn’t work for me.” As it stands… it’s just frustration.

I really do wish them well on it, but I think for now, I’ll be sticking with NDoc.

I’ve been lamenting the fact that JHymn can’t deal with the latest iTunes DRM. So much so that I haven’t upgraded to iTunes 6 and have consequently been having odd crashes whenever I search the iTunes store. (Why remove the DRM? Because it locks me into only playing the songs I bought through iTunes - for example, the iPod support on Xbox 360 won’t let you play protected songs, and I think I should be able to play the stuff I bought wherever I want.)

Seems there’s potentially a new sheriff in town: myFairTunes6 v0.2b

Might have to get Stu to give this a go. (It’s his turn to be the guinea pig.)

Jenn and I went to see The Wicker Man yesterday. While it doesn’t seem to be soaring in the ratings on IMDB, I didn’t think it was all that bad.

The premise of the movie is that Nicolas Cage is a cop who witnesses a traumatic accident. While he’s taking some time off to get his head straight, he gets a letter from an old girlfriend (played by Kate Beahan) asking him to come to this isolated commune she lives on called Summersisle because she needs help finding her daughter. When he gets there, he finds that there are all nature of weird things going on and its up to him to figure out what the real story is.

I thought it was OK. I wasn’t blown away or anything, and I guessed the twist at the end with about half an hour to spare. I also had an issue with Beahan’s mouth the whole time - her lips are sort of weird (too large? misshapen?) and I had a difficult time concentrating on what she was saying when her mouth was moving. There was also this odd disconnect between the accident that Cage witnesses at the beginning of the movie and his arrival on the island. What relevance did that have? Was it just a mechanism to get him into convalescence so he would be receptive to getting the letter? A plot convenience? I’m still figuring that out.

That said, I’ve seen some pretty sucky movies lately, so I can’t really bag on this one too bad. I think it’d be a decent rental, but you might not want to pay full price for it at the theater.

Interesting item I didn’t know - it’s a remake of a 1973 movie. Kind of makes me want to see the original to see if it’s any better. It’s got almost double the ratings as the remake, so maybe it’s doubly good.

I had a pretty decent Labor Day weekend, but I’m tired this morning, so I’m drinking an Amp Big Rig, possibly the largest can of caffeinated beverage I’ve ever seen. Oh, hell yeah.

Friday night not a lot happened, or at least nothing of interest that I’m remembering right now. That’s quite alright, though, as a quiet Friday night after a long week at work is just fine by me.

Saturday morning we were up bright and early and headed down to Wilsonville for the Hollywood Video warehouse sale. They opened the main office for a big previously viewed video sale where movies were between $2 and $6 each. We met my parents down there and good thing, too, because they got there far earlier than we did and got a decent spot in line. You should have seen the line! Unreal. And due to fire code, they could only let 100 people in at a time, so the line was moving sloooooow. But we got eight movies of varying cost for a total of $38. Not bad.

After that, we headed over to Fry’s to see what was cool and new. I ended up getting MacGyver Season 1 for $20, which is a total steal.

We then headed to the mall to burn a little time and had someone comment on how they liked my shirt and someone else comment on how much better my car looked than theirs. Can’t say the compliments didn’t boost my ego a bit. Just a tad. I am the center of the universe! Okay, better now.

Didn’t really do much at the mall. Walked around, looked at stuff we can’t afford, etc. Had a little lunch, then headed over to pick up Jenn’s dress from the bridal shop. After that, headed home and… watched movies. Woohoo!

Sunday Stu came over and we put in some units on Oblivion. Actually got several hours in on that and finished quite a few missions. On lunch break we went to get our tuxes measured for the wedding, so that’s an item checked off the list of things to do. We all followed the units up with a Flavor of Love marathon (catching us up to current) and called it a night.

Monday was the downer of the three day weekend. I always have that dilemma on the long weekends of when to do the work that needs to be done. If you do it at the beginning, it sets a bad tone for the rest of the weekend. If you do it at the end, it makes you feel like you wasted the last vacation day available to you by doing work.

I fixed the stupid trim around the front door first thing. Of course, I had to sand the existing paint down to get rid of the majority of the brush strokes the painters left, which made the whole area dusty, so I got out the broom… and promptly fucked up the finish on the front door. I guess I figured the super-mega-paint they were supposed to use would hold up to a brush off with the broom, but not so. Well, nothing to be done about that now. You don’t notice it from far away, but up close, it’s there. Bah.

So, yeah, the trim got fixed. Then I went in and sanded down the tops of two doors in the house that wouldn’t shut (or shut really tight, as the case may be). All doors work, now, but what a messy nightmare.

Jenn had some stuff to do at the mall, so I tagged along and ended up picking up Kameo Elements of Power for like $28, which is pretty decent for a 360 game. I tried the demo and it was OK, and after realizing I will never finish GRAW on hard mode, I thought it might be fun to get a new game. I have a few that I should probably play out on the online modes (I have the stupid Xbox Live Gold membership but somehow rarely actually get online) but just haven’t done it yet. Maybe that will be something to do as the money gets tighter come holiday time.

Anyway, went to the mall, got the game, had some lunch… during which Jenn got something on her shirt, so we had to get her a new shirt at Macy’s. Found the cutest little G-Unit shirt for her, totally on sale, so we got that. My little gangsta baby is hot hot hot. Then we headed to the theater and saw The Wicker Man.

That was pretty much the weekend. Not a bad one, if I do say so myself.