This little HTML renderer in my head
Back in 1995 when i finally joined the Internet wave (i know, kinda late), i was somewhat puzzled by the seeming simplicity of HTML (compared to the nice layout it was able to produce). This wasn't the first time that i had to learn a layout language (the first one was circa 1988 when i learned a custom printer syntax for making fancy ads on selling my sister's apartment). So, i printed out the HTML specification (and back in the days of HTML 3.0 it was pretty straightforward), came back to the dorms, wrote (and rewrote) quite a few pages by hand (on paper) and went back the following morning to the computer lab feeling like a budding HTML guru.
Back in the day it was fun feeling like that, when the Netscape composer first came out and totally screwed my perfectly aligned HTML pages. Not to speak of the horrors of the first versions of FrontPage and long-deceased (is it?) HotDog (i think that's the name). But i digress.
One of the major points that set Java apart from C++ was Javadocs. You know, you comment your code (or at least you're supposed to), run this clunky command and it spits hundreds of thousands of HTML pages, all interlinked to create a falsehood of well-documented project. Not only that, it can also take any (valid or invalid) HTML in it. It just doesn't care. So, instead of writing a nice documentation in Word (the fearsome), HTML (the tiresome) or even LATEX (the cumbersome), you just stick the "This function returns the value of XXX attribute" in all your getters and your manager is satisfied (as time goes by you don't even have to type it yourself, just let the IDEs do it). But what about code samples, formatting and such? Don't worry, just stick HTML in it and it'll be fine...
Fine for whom exactly? I don't know about you, but i only read (actually read, not dismiss the annoying IDE popups every time i accidentally pause with the cursor over some damn method invocation) Javadocs on JDK classes. When i write Javadocs for my side projects, i don't really go and explore the entire web of generated HTML. It's enough for me that the javadoc generator didn't issue any warnings. But i digress once again.
So when i come to comment some function and provide a nice explanation about what it does and perhaps throw in some code sample, i need to start thinking in HTML (instead of thinking about the content). It gets even worse when i need to modify existing Javadoc section. That little HTML parser we all have in our heads for the past 10+ years start chewing on some (hopefully valid) markup and humming "Hey, look here, what does this ul do here in the middle of the table?"I have to admit that the HTML parser in my head gets better and better every year. You know, when you learn a foreign language and you know that you've suddenly become good at it? It's when you read something and don't translate it to your native language, when instead it goes straight to the images and associations in your head? The same with HTML for me. You know, like Cypher says about Matrix code, "All I see now is blonde, brunette, redhead."
And this is not good. We're not supposed to be HTML renderers. We need to focus on the code. If we need to write documentation inside the code, the IDE should provide us with WYSIWYG in-place editors (something like this is planned for Fortress). I hope we will be there in 10-15 years. I think by that time the keyboard and the mouse will be replaced by something more "human", like hand-writing recognition fused with touch-pads and eyeball tracking devices. When you want to add a diagram (like in JAXB architecture document), you just draw it inside the code and let the IDE translate it to a IDE-independent format that can be easily processed and converted to great-looking documentation. If i want to change the in-code documentation, i just start dragging stuff around, erasing bits that i don't like and adding pieces that are missing.
And last, but not the least. I don't get this "Wiki-boom". I mean, is the syntax supposed to be simpler than HTML? Here, any sequence of prime-Mersenne dashes followed by matching number of plus signs is interpreted as a heading. Right guys, so more flexible than <h2>. At least with LATEX you get real low-level control. We all laughed when Brooke Shields' character was fooled to believe that Drake has an evil twin named Hans. This is just another syntax for the same thing, just one more renderer to stuff in your skull.