Building TyNETv5 Pt. 6 - Intermission

2013.06.23 20:28:45

imageAs I was preparing lQuery for release today I noticed that I still needed a couple of other things before I was ready. One of those things was that my base syntax macro was actually not working properly (variables weren't being handled right), so I had to spend quite some time rebuilding and debugging that. Then I realized that I wanted to have a proper documentation of all the functions ready for release. Since I'm lazy and a programmer I thought I'd use lQuery to write a library that automatically generates HTML documentation files for a given package. This turned out to be a tad more complicated than I initially expected, so I couldn't finish it today. And that's basically why lQuery is delayed, oh no!

I did manage to finish writing all unit tests for lQuery on Saturday evening though, so that's cool. I still need to adapt it for the changes I made today though, but so far it's been running great. Writing the tests also forced me to check if the functions actually worked properly (which I hadn't for some) and it helped me fix a couple of bugs that were still in the system, so that's really neat too. Plus, now I have a way to check if any of my future changes break all the things, hooray!

Granted, since I'm new to unit testing (this is the first time I've done it, gasp) there's probably a bunch of not-quite-complete tests in there that should be expanded so that more of the behaviour can be checked. But I think I've got the main uses under control, so the library shouldn't break down immediately without me noticing. Even though lQuery is heavily based on jQuery and borrows most of its functions and their purposes from it, there's some minor differences for a couple of functions that I implemented because they seemed more sensible to me. Plus, there's the obvious difference in the general system of how this is all handled that needs to be properly documented as well. As such I'd rather put off releasing the library for a while longer still until I have a proper documentation written.

Since I do write docstrings for all my functions, I obviously don't want to painstakingly put this together by hand and update it every time I make changes. This is why I wanted a documentation generation tool. I already knew about Edi Weitz' tool, but it doesn't generate it in a way that I would like and I thought this would be a good first real-world use case for lQuery. So I set out to write a tool like that myself.

Unfortunately this turned out to be a bit more difficult than I imagined it to be, mostly because of the way Common Lisp works, so I had to spend a lot of time finding out how to get the information I need. I'm still not done, but a good chunk of work has been finished and I can use Documentation-Template as a reference for things I can't figure out myself, so I should be able to finish this additional library by tomorrow and hopefully also release lQuery along with it!

This tool is going to be useful in the future too as I can deploy it for any library I write. Thanks to lQuery based design, I can also easily provide templates for it to fill the required information into. Simply pass a template node and a bunch of selectors into the function and it'll be able to use those to put the information in its proper place and then put everything into the document. This allows for immense flexibility on how the HTML is actually constructed in the end and puts almost no constraints on your markup preferences, which is a huge win.

So yes, that's all pretty fantastic. On another day I took a look at Hunchentoot and how to make it work with my intended system. I've got the beginning of an INIT sequence set up, but I need to think a bit more about the architecture before I can continue. Mostly what I need to figure out is what kind of resources should be global, how startup and shutdown of a server is handled, how modules can register themselves in the implements system and so on. It'll be a while before I make actual code progress on this, but I'll probably post another update with new thoughts sometime soon.

Next up: lQuery and lQuery-Doc release. image

Written by shinmera