Today we've reached the feature complete milestone for OmniaMea 1.0. We're only a little late from the originally planned date, and we didn't have to cut any big features to make it. I feel that by now we have a product that covers a very wide range of personal information organization scenarios, from simple (flags and workspaces) to advanced (custom properties), and a very wide range of information types.
The key areas we are planning to address next are UI look and performance. Our designers have done a great job creating sketches for our UI, and now the time has come to turn them into real UI. And as for performance, we have planned improvements in all areas of the program, starting from the lowest level data storage and text indexing code and up to the high-level UI.
As we're preparing to release the open API for developing OmniaMea plugins, I'm currently investigating various solutions for generating the API documentation. I've long resisted the idea of writing documentation as the XML doc comments (prefixed with ///), because the comments clutter the code pretty heavily - much more than JavaDoc comments (if you don't use too many HTML tags in your JavaDocs). However, the comment editing experience provided by Visual Studio (type three slashes and get a full template for the comment block) is hard to beat, and I couldn't talk Resharper developers into providing a similar solution for JavaDoc comments (even though they're equally supported in Visual Studio 2003). Thus, I gave in and decided to do it the standard way.
Now I'm looking for a tool to generate the final documentation file. NDoc deals with the generation part pretty well, but I'd like to include a set of manually written pages (Developer's Guide), and it looks like all that NDoc offers for that is a list of files to include separated with semicolons... which is not quite user-friendly.
I've tried using Document X, but aside from general slowness (10-15 seconds to open an empty contents file for editing is a bit too much for my taste), it is simply buggy. I could live with being suggested to edit the return value description for functions returning "void", but ignoring "ref" modifiers on function parameters makes Document X totally unusable. The API signatures in the help file must be correct, period.
Another problem is generating documentation for an XML file format. Our OpenAPI allows to define actions, resource icons and some other information declaratively in an XML file, and I'd like to be able to easily generate documentation for the XML format. I've found several tools for documenting XML schemas (Document X does that too), but they don't seem to do the right thing. They do a pretty (sometimes very pretty) printing of the XSD definition, and that must be great for those who want to understand how the XSD is set up - but not for those who want to quickly create an XML document matching the schema. Microsoft does a great job with their schema documentation - concise and to the point - but, as far as I know, they never released a tool that would allow me to generate such documentation. Is it time to try hacking NDoc to add this functionality?..
As usual, pointers to tools that could help me solve the problems are very much welcome.
As I've started to write fairly regularly about technical topics to my LiveJournal, I thought I might as well cover these topics here... it's better than no blogging, in any case.
One of the few remaining features that we had planned for OmniaMea 1.0 is bookmark synchronization with Mozilla/Firefox. Today we have finally investigated what this feature really costs, and the results were not too pleasant.
First of all, in order to correctly locate all Mozilla profiles, we would need to create a parser for the profile registry, which is stored in a custom binary format. It looks as if Netscape developers created a new universal, powerful and extensible data format for every single data storage task that they encountered during development. While the format of the profile registry is much simpler and more reasonable than the history.dat format, a simpler general-purpose format (like XML or even RFC-822) would have suited the task just as well, and would be much easier to use for external developers.
Given the time constraints, we decided that we won't currently develop the profile registry parser, and will simply scan the two profile roots (Mozilla and Phoenix) and offer the user to choose one of all the profiles we will find.
A much more significant problem is that export of bookmarks to Mozilla seems totally impossible. The reason is that Mozilla always saves its bookmarks.html file when exiting, and that would overwrite any changes that we could make in that file when bookmarks are added or changed in OmniaMea. Synchronizing the bookmarks when Mozilla is not running is pretty much useless, because in general there is no reason to ever close the browser. (Myself, usually I start the browser as soon as I power on the PC and keep it running until the next reboot.) And I don't know of any way to update the list of bookmarks in a running instance of Mozilla.
On the other hand, while the structure of the Internet Explorer favorites folder is considerably more complex than a plain-text file, we can parse it entirely using the operating system API, and we can create or change favorites at any time with no problems.
And even though the open-source nature of Mozilla allows us to solve these problems ourselves, and we probably could spend a man-week or two to develop the patches and push them into Mozilla 1.8, this makes no real sense to us. First, a majority of users would still use earlier Mozilla versions, and wouldn't be able to benefit from our work. And second, with our small team, we'd very much rather spend our time improving our product, not some other loosely related ones.