Years ago I was told by an asshole boss at a company I worked for that I was going to be “fired” if I didn’t “document my code” (although it should be noted that I maintained a department library of dozens and dozens of white papers on our software design… but he was too much of an asshole to care).
To shut him up, I showed up to the scheduled meeting a month later with a stack of paper as tall as two dictionaries, full of detailed information about every single class, method, and function written by our six-person development team. I determined from the start that there would have been no way I could have done this manually, so I spent weeks of my personal time building a documentation generator to handle the chore with its own Pascal language compiler.
Although barely working, I have brought my old documentation generator back to life and built a barely-working barebones web front end for it online for the purpose of documenting my Delphi CommonX library, but don’t get too eager to read much of it because the documentation sitting on the documentation server is super sparse and simply for the purpose of testing a new searchable database of classes and symbols.
I was barely 25 when I wrote most of this code (and I turn 45 in just a couple of days). So getting it to so much as compile was quite a challenge and occasionally comical as I reviewed all the dumb code I wrote nearly 20 years ago.
My goal back then was to create something that would compete with UML modelling tools, such as Rational Rose/ModelMaker and combine that with doxygen, which was very much in its own infancy back then. If I had the time and resources to work on it, I am confident that I could have a viable competing product to offer the world, but life and work has been pretty busy over the last 20 years, despite my prolific nature as a coder.
Rational Rose was always a big pile of shit that constantly crashed and barely drew charts correctly. I don’t know if they ever improved the software, but I stopped looking, because I lost faith in that garbage decades ago. I didn’t like Doxygen, because Doxygen forced devs to inject horrid, unreadable XML tags into comments, something that I thought was dumb and disrupted the readability of my code. So I wanted to do something that fit into Delphi in a natural way, in comments, and was readable in Web form while also being readable directly in the code at the same time. I also started on a UML chart creation tool.
Whereas the server is barely functioning with some super barebones lists of symbols, the current operational status seems to indicate that the hardest piece, the parser, is functioning well enough to support finding all the classes and units and such, although it is missing member variables/fields and tons of other stuff. Furthermore, most of the classes of commonx are completely lacking any compatible comments… because I haven’t used this thing in years… 20 years to be exact. Although there are at least a few units out there like this one that will actually generate more than nothing. My main reason for even posting about it in my blog at this time is to give the web crawlers an opportunity to find it. Hopefully, by that time it will be more mature. I will be sharing this documentation with my colleagues in the business, so I have plenty of motivation to fix it up.
Bringing it back to life is, also bringing in some needed changes. The documentation parser is getting more sophisticated and is close to supporting most Delphi 11 language features. A whole new relational database stores the documentation. I may consider converting it to use clickhouse.
CommonX is a set of libraries for Delphi that are available on GitHub at adaloveless/commonx, however, the current version up there is way behind my personal repo. I dislike working with GitHub. I put commonx up there reluctantly a couple of years ago at the urging of others… but when it didn’t get any traction, I moved my personal development back to SVN, only occasionally pushing updates to GitHub. Maybe if I document it a little better at all it will gain a bit of traction. An update is due…. and soon!
Hey man, congrats on reviving your old documentation generator. It truly shows your dedication to Delphi. I’m curious, what kind of databases did you use in your initial implementation 20 years ago, given the relatively less sophisticated DB options available at that time? Also, I can clearly see your distaste for UML modeling tools and XML tags in comments. Would you say that your frustration with those systems was the primary driving force for you creating this doc generator in the first place? I’ve dabbled with Delphi in the past but never to the extent you have, it’s fascinating to see the level of commitment and time you’ve put into this.
Hey George Williams, curious about the database choices too! The frustration with those clunky UML tools might’ve been the spark, but reckon the real driving force was proving that boss and the pragmatic need to simplify the doc process. Not to mention the sweet satisfaction of solving a problem with your own ingenuity. Twenty years on and still improving it, that’s dedication! Ever thought about how current tools could improve or simplify old code? It’s wild how tech keeps evolving.
Improving old code? Isn’t that like teaching an old dog new tricks? Ha!
Sometimes, “old dogs” are foundational and just need a fresh perspective!