nythrix's picture

The joys of documenting software

I've been fiddling around with a new version of Cloo for about two weeks now. 90% of that time has gone into documenting bits. Which is an extremely vivid and exciting hobby.
No wait, it isn't. In fact, it almost put me in such a deep coma that would've certainly been followed by death from boredness, if it wasn't for the heat that's been frying my hometown in the last 50 days. Apparently, you can't type yourself into a coma, if you need to drink and eventually sweat a liter of water every 15 minutes.
Anyway, there I was during the night, tapping the keyboard, turning my chair into an excquisite waterpool and whatnot. By the time I was writing/copy pasting/checking the same line of documentation for the 14th overloaded method, I felt like missing the old C/C++ #define.
Sure, there's <include>. Problem is Doxygen thinks that's dog poo. And what's the point of putting documentation into an external file, cryptically linking it with the code just to export it into another external file again? It sort of blows the benefits of documentation and code sitting next to each other into the middle of last week. And it surely doesn't enhance my user experience, if I need the same strings in both code and documentation.
I'd really love a simple: #define SYMBOL "a bit of lorem ipsum in here".
What's wrong with that?

If you guys have any experience in this area, I'd like to hear about it.