News and updates concerning the ZenDoc documentation tool for ActionScript http://www.zendoc.org/ Trevor McCauley, senocular@hotmail.com en-us (01-20-07) Lately I haven't been able to work on ZenDoc. I've been busy with work and keeping up with the holidays among other things. I also got a Nintendo Wii and have been playing around with that a bit. I took a particular fascination in the Mii characters and started a side project for editing them online: Mii Editor. This project has been taking most of my free time as of late and I probably won't get back to ZenDoc until I've completed it. I'm still hoping to get the next version of ZenDoc out before the next CS release. That's the plan. :) http://www.zendoc.org/news.php (12-10-06) I've been working on version 2.0 a little here and there (though I have been really busy with work lately) and so far things has been coming along nicely. Presently it seems members are being inherited in subclasses from their superclasses and it seems types are recognized when one class within a collection uses a type defined in another class of that collection, but I also wanted to mention a couple of other features that will be in 2.0 that I hadn't mentioned before. These include: Access to a class's source code. This will allow templates to include a parsed file's source code directly within the document if desired. Support for sorting. Now TemplateBeginRepeat loops in templates can be sorted alphabetically or numerically in ascending or descending order and based on any code or comment value. An Ignore Whitespace option. You now have the option of ignoring whitespace within tempate tags which should help clean up the generated HTML. A new TemplateBeginCommand tag. This tag lets you run a custom PHP function on the contents of this tag block. This creates a new level of customization for templates not before possible. Though a working prototype is still a ways off, I will intend to have a beta version available for download (though not live as pretty much all the new features are for local documentation) when ready. http://www.zendoc.org/news.php (12-09-06) Apparently my site had a mid-life crisis and decided to go all corrupt on me. This also happened right around a scheduled backup making my last, usable backup a week or so old. I lost the new site design (which I should be able to bring back I think) and there was a while when the online version of ZenDoc rolled back to the beta. ZenDoc 1.5.1 is back up now, though. And everything is mostly OK... for the most part http://www.zendoc.org/news.php (11-24-06) Work is going good with ZenDoc 2.0. I'm getting more done faster than I thought, though there's still a long way to go and I've been pretty busy with other things lately. In addition to what was mentioned earlier, there will be a few more additions that are pretty useful and add a lot of power to templates, especially for those looking to really customize their output. Of course at the same time template creation just got a lot more complicated. Other than that, I think I got inheritance and type linking working between classes (assuming types are part of the same package documentation) which was probably the biggest hurdle to overcome. Now I think there's just a lot of grunt work and making sure things work the way they're supposed to as well as updating the documentation to reflect what's new. http://www.zendoc.org/news.php (11-14-06) Thanks to a wonderful habit of mine - spelling 'pacakg... DAMMIT! I did it again. Slowly now... I tend to misspell p-a-c-k-a-g-e when I type it. So, thanks to that, there was a bug where package paths were not being recognized for ActionScript 3 files processed by ZenDoc. Just as well, they were being placed in a separate list in templates making it troublesome to access. Anyway, 1.5.1 now corrects that and loses the packages list in templates (no templates available here were using it) and places it in the class definition as is the case with AS2 files. Additionally: support has been added for the Javadoc serialField tag, Javadoc tags are no longer case sensitive, and returns tags are remapped to return and exception tags are remapped to throws in templates (allowing for an easier way to catch those synonymous tags in templates). Download it now. http://www.zendoc.org/news.php (11-13-06) I've been toying around with a lot of what could be possible and what I plan to have available for ZenDoc 2.0 - probably the last major release to come. Here's basically what we're looking at (at this point in time): Support for library or package documentation. This means instead of documenting source files individually, you have the option of documenting many source files as a collection for a package or a group of packages (this would only work with local documentation) Recognition of documented file types. When documenting collections, ZenDoc 2.0 should be able to recognize references to other classes being documented and provide links to them Recognition of inheritance. If documenting two classes in a collection where one class is inherits from the other, the subclass should be have access to the methods it inherited from its superclass. Support for external assets to be referenced by templates. This would let templates use and reference external data i.e. external css, js, and images etc. A new variable template tag. This tag (TemplateBeginVariable/TemplateEndVariable) would be used to store values or template blocks which can be reused throughout the remaining of the template. Saving values lets you be able to reuse or compare text generated earlier in the document (new templates will demonstrate their use) while saving template blocks can reduce redundancy in your templates by letting you only define a commonly reused block once (e.g. having the same template blocks used in constructor, variable, method, and event loops) Better command line support. This essentially meaning having more control over output using command line arguments Improved documentation. Just having more documentation and clearer examples, especially for people just starting with ZenDoc And possibly some better support for some of the features in Javadoc Some of these changes could result in a lot of code reworking or rewriting so I wouldn't expect a working preview of 2.0 any time soon. http://www.zendoc.org/news.php Release 1.5.0 is now final. I updated a few of the templates to some extent, and I think the default is good enough to remain the default template. Additional changes include: Updates to the documentation to include descriptions of available options Changes to the view link for templates (so that its now possible to open in a new window or browser if desired) Inclusion of a new Basic template which should hopefully help people in making their own Version 2.0 is next in line. With that will come better support for multi-class or package documentation. I'm also thinking about a possible way to simplify templates a little more, so we'll see if that's possible (or easy enough to implement). http://www.zendoc.org/news.php A few new updates: 1) A minor interface tweaks; External Files pane selections are now remembered when applying new options 2) when using the web URL (or the Reusable option in the External Files pane), the options used are now taken from the ZenDoc ini file instead of the last remembered settings as it was doing before and 3) I think I fixed the command line tool. Apparently this broke with some other updates but I got it working again. I'm also still working with the templates. Once I find something nice for the default, I'll update the others and try to take the release out of beta before starting to work on 2.0 features (and, yes, expect many versions of 1.5.0 to be pushed out this way without distinction - I'm lazy). I also added a menu to the web site here. That should help in getting around it a bit. I'll also see what I can't do about adding some basic tutorials such as basic usage and things like using the command line options in tools like SE|PY. http://www.zendoc.org/news.php Having returned from MAX, I'll try to get back to working on the updated ZenDoc templates. Chances are in working with them I'll still have a few bugs to squish before a final 1.5.0 release (which currently remains in beta primarily because of the templates). Moving on to V2 I'm looking towards imports parsing, though probably with the commenting requirement, and recognizing associations with other classes and support for package-based documentation rather than individual files. http://www.zendoc.org/news.php Today I noticed ZenDoc was in the comparison chart of documentation tools on osflash.org despite ZenDoc not having a page there. Naturally I took the appropriate action and removed it from the chart. But then I said to myself, "Self, why not just make a ZenDoc page there?" So I did that instead ;). ZenDoc on osflash.org - and yes, it pretty much just links here, but its good to get in with the rest of the OSS crowd (even though in that chart ZenDoc is comparably pathetic). http://www.zendoc.org/news.php I've been toying around with a new default template for ZenDoc aptly named "Default.html". I'm still playing around with it now, and it's still pretty simple, but it implements combined getter and setter properties. You can see this if you create documentation for the local Cursor.as file using the Default template in ZenDoc (note the position property). I'll probably spend the next couple of days working on what I want the default template to really look like, though I imagine I won't finish before MAX sweeps me away, so it may be a couple of weeks before anything final comes out of this. http://www.zendoc.org/news.php Continuing to refine 1.5 before coming out of "beta", view links have been provided for templates (which are still to be updated), a Reusable URL option has been provided for URL-based documentation, and the Combine getters and setters option should now be code complete and functional for templates that make use of it (i.e. definitions in code are now lists and not values). http://www.zendoc.org/news.php If working with Dreamweaver to save custom templates for ZenDoc, you may find it annoying that DW will constantly be asking you to save as a site template when you may not want to do so (rather just having it as an HTML file). To get around this, I created a simple Dreamweaver extension that adds a new save option Save As Is. This is like Save in every way (even accessible from the File menu) but it does not prompt you with the Save as Template dialog. You can install this and re-map your keyboard shortcut for save to this command instead. http://www.zendoc.org/news.php Added a simple RSS feed for the news. www.zendoc.org/rss/ http://www.zendoc.org/news.php There was a small issue where checking the root folder checkbox would select or deselect all the options checkboxes. That has been fixed. The defaults button also now correctly restores defaults instead of just resetting form data. http://www.zendoc.org/news.php zendoc.org is currently getting a slight make-over, so you might find some links are not currently functioning. Please be patient; thanks! http://www.zendoc.org/news.php ZenDoc has now moved to its own domain! www.zendoc.org http://www.zendoc.org/news.php Released version 1.0. This is currently the live version as well as the version available for download. For changes, see the version history from the help link in the demo. http://www.zendoc.org/news.php Updated the download version to 0.10.1. This should fix some of the issues in 0.10.0 plus a few other minor additions and less obvious fixes. The demo version remains 0.9.9. I still have a few changes to 0.10.1 until releasing a 1.0.0 version. I might hold off multiple file/package functionality until later. http://www.zendoc.org/news.php I am aware that there are some issues with the current release. I'm still working on them. I'll try to get a new (better working) build up sometime soon. http://www.zendoc.org/news.php Released 0.10.0. Still not a 1.0 release, though a couple of bugs have been fixed. This would have been a 0.9.10 release but I wanted to get it out before I tried to get the other features in there (if that makes any sense). http://www.zendoc.org/news.php Created a project page for ZenDoc and future senocular.com projects - a very simple layout for housing project information. http://www.zendoc.org/news.php Released 0.9.9. This marks the first release ZenDoc can be downloaded. I still want to look into implementing a means by which packages can be more easily documented at once. Nevertheless, I think ZenDoc will benefit from now having a downloadable version. See the help documentation for more information on the release. http://www.zendoc.org/news.php Created a project page for ZenDoc and future senocular.com projects - a very simple layout for housing project information. http://www.zendoc.org/news.php Released 0.9.8 cleaning up some interface elements and, most notably, a new name for the project: ZenDoc. The next release should be a bug fix release followed by 1.0 which will be available for the public to download. Given the new updates in 0.9.8 and 0.9.7 (see version history in Help--which may also need more updating--for more information) some templates need to be updated to use the new template format. The current templates, however, should still mostly work well enough now. After 1.0 I'll try to release a few more templates as well as maybe reviving the option to allow users to upload their own. http://www.zendoc.org/news.php Resumed work on AS2Docular after a summer hiatus, fixing bugs and cleaning code for version 0.9.7. http://www.zendoc.org/news.php Fixed a small pathing problem preventing sample templates from being recognized in the Standalone section. http://www.zendoc.org/news.php Updated to a version of the new interface. It represents version 0.9.6 of LateDoc, leading the way towards a downloadable version which should be available soon (probably before a version 1.0 release). http://www.zendoc.org/news.php Fixed a small problem with the MMLiveDocs template preventing usage from being displayed (thank you Peter for pointing that out). Released version 0.9.5. http://www.zendoc.org/news.php I've been tweaking some of the templates setting a few conditions to ignore content headings for content that doesn't exist. I'll try to get more custom templates up soon as well - as soon as I can think of something original. In the mean time, I think I'll be working on an interface for the personal version - a version you can download and use on your own server (local or hosted), which should allow batch documentation and templates that create multiple files from one ActionScript source file. I've included a simple template, MethodFiles.html, that shows how the TemplateBeginFile template tag can be used (very basic) where the output remains one file, providing headings representing where a file begins. More complicated templates would be necessary to fully take advantage of this multiple-file export. http://www.zendoc.org/news.php Added a Natural Docs and an ActionDoc HTML template. It's got your basic look and feel and currently only lists methods and properties. In fact, I don't think many of the templates are THAT comprehensive, though some are pretty close. For example a few templates will provide a properties (or fields) heading even though none exist for the class. I'll try to improve them sooner or later. Don't forget you can submit your own as well (or submit fixes to the current templates if you want). http://www.zendoc.org/news.php Version 0.9.4 released with some minor updates, mainly the inclusion of the TeplateBeginFile tag. Also included an option to submit your own templates or ActionScript samples. http://www.zendoc.org/news.php