Sneak Peak: BLDocs documents AS2 code

We’re working on a documentation generator for ActionScript 2 that parses code commented with the JavaDoc style syntax to create HTML help, Flash help, or any other type of documentation. Here’s a sneak peak at the output and feature list…

When we started documenting the next version of our charting components we realized that we need a generator with a lot more features than exists in any available product–our goal is to have all documentation generated without any manual post-run tweaking.

So, we’ve begun work in BLDocs, an AS2 code parser and documentation generator. Here’s the initial feature list we expect to include in the first release.

  • Read AS2 files and parse both code and comments.
  • Recursively parse all files in a directory and sub-directories.
  • Parse class info, functions, properties, and all meta tags (events and such) from code even without comments.
  • Support for any comment tag without requiring program modifications or extensions to support new tags.
  • Support for either collapsing or preserving white-space in comment tags (particularly as related to the @example tag).
  • Support for comments with leading asterisk or without.
  • Handle meta-tags intelligently where a class based meta-tag (event) can have it’s own complete set of documentation but a function based meta-tag (inspectable) is owned by the function and doesn’t have it’s own comments.
  • Write the parser such that it creates an internal abstract ActionScript tree representation so the program can be extended for any output format.
  • Support for documentation collapsing (collapse the inheritance chain for documentation purposes).
  • Support for documentation-only function/property overrides–provide new documentation for a base-class function even if the function isn’t overridden in the class.
  • Support for documentation based access levels (public, internal, package, protected, and private).
  • Filter classes based on access level, meta-tags, comment-tags, or package.
  • By default output an all-encompassing XML format and support XSLT translations to final files.
  • Support a command file interface that allows parsing multiple class paths, specifying various translations to run on XPath based node sets each with their own destination directory.
  • Include XSLT translations and command file for JavaDoc style framed HTML output listing packages, classes in each package, package summary pages, and class pages that list all class info in one page.
  • Include XSLT translations and command file for Flash MX 2004 style documentation with ActionsPanel, TOC, Index, Search, and Contents page generation.
  • Make a nice GUI for the whole application. Right now it’s command line and we may release it without a GUI since it is a developer tool.

Here’s a snap-shot of the HTML-style generated documenatation for our charting components.

Screenshot of BLDocs generated output

If there are other features not listed that you would like, please drop me a line and I’ll add them to the list for consideration.

This entry was posted in Uncategorized by Sam. Bookmark the permalink.

25 thoughts on “Sneak Peak: BLDocs documents AS2 code

  1. The application is written in .Net so if we create a GUI it will be written in .Net. Our goal is to have all functionality controllable via command-line first.

  2. Nik,

    The XML format is pretty straightforward listing of the classes. It lists all packages and then one entry for each class, listing the description, all meta-tags, all comment-tags, all properties, methods, events, and styles, including inherited properties/methods/events/styles and which class they’re inherited from.

    The goal is to have a complete separation between parsing/filtering and generation where the parsing/filtering is done in C# and the docuemnt generation is done in XSLT. That way anyone can extend the generation however they want without needing to edit the C# program in any way.

    Sam

  3. I was just working on a such app, but online, written in PHP … Will you use a JavaDoc style, or a FlashDoc (gmodeler) one ?

    Waiting for you app will be very long !!! :o D

    C ya ! ;o)

  4. Our app writes to an intermediary XML file which we then run a bunch of XSLT transforms on to create the final output. We’ll include both JavaDoc and Flash MX 2004 help style output.

    The whole reason we’re outputing and all-encompassing easy to use XML intermediary file is so people can modify the XSLT’s to their own needs or create their own for whatever format is required.

    Best regards,

    Sam

  5. Do you know when you will make your XML format available ? It would be great for me to have the same intermediary format, for the doc rendering to be independent from the parsing engine …

    Thanks, and good luck for this great project ! :)

    C ya ! ;)

  6. Thank you for the good news,
    I have been working (in my free time) on a AS 2.0 / JScript .NET code and documentation generator (written in C#). The application will be released as a Windows Forms application (will require .NET v. 1.1). It is working in the reverse direction; it creates code from the Xml representation of CodeDom and it creates documentation via Xslt.
    Here is my current schema for the CodeDom representation:
    http://www.zoode.org/temp/asbot/asbot.codegen.schema.xsd

    As a side note, a similar project for C# can be found here:
    http://www.c-sharpcorner.com/Code/2002/June/CsCodeParser.asp
    (parses CSharp code to basic CodeDom).

    Best of luck,

  7. Feature Request: Parse C# style doc comments as well as JavaDoc style.

    ///
    /// my summary
    ///

    /**
    * my summary
    */

    If you want to make it cross platform, I’d be happy to port it to either Java or C++ when you’re done with the .NET version.

  8. That’s a good suggestion Darron, we’ll add that to the list of features. In the meantime if you could send us some commented code for testing that would be great. Preferably AS2 code but C# code would be fine too.

    Also since we haven’t made any decisions on how we plan to release the product at this time, we’ll have to think of other ports as needed down the line.

  9. We’re running a very small private alpha right now and will be opening it up to a public beta in a few weeks. Production release is still at least two months off.

  10. The separation of the display and parsing is genius. Using XLST to transform the data into a common format will be easy.

    Thanks for all the work you guys have put into it. Let me know if there is anything I can do to help.

    Thanks,
    Danny

  11. Hello all swingers. More information for your life.
    Since HDCAM SR offers a dual HD SDI option, recording 4:4:4 RGB video with an all but invisible compression, it is an option to use it instead of 2k. The resolution is quite similar (1,85:1 – 2048×1107 vs. 16:9 1920×1080) – and it is easier to handle. If the colorist knows what they’re doing this is quite attractive (and cost-effective) for independent film makers. It is done like that at some European post houses.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>