Emak Mafu Development Blog

Icon

London Digital Week

Compiling Relevant Classes in ASDOC

I have spent some time getting asdocs to work the way i want t to. There is not much information on the net about this tool yet and so i thought it might be nice to share what i have learnt.

The task i was assigned was to generate html documentation for any given project, thats pretty simple. The twist was to only document the classes relevant to the project. With a library full of source and swc format classes this became quit a struggle. My solution was to make an ant script that performs the following functions.

Create a manifest of all classes in the lib path

The classes in our the lib directory are in source format (they are all *.as files). These classes are not important to the documentation, we do not need to generate asdocs for the Tweener library for example, as this documentation already exists elsewhere. By default asdocs will document any class which has been used in a project. If we use a Tweener class, asdocs will document this class being used along with all the components of the tweener library that this tweener class references, this is a lot of irrelevant information. For this reason i generate a list of all the classes in the lib directory, this list will be passed to the asdoc tool which will exclude them from documentation. The ant code is as follows;

<!–the location of the lib folder relative to the project directory–>
<property name="libraryFolder" value="lib"/>

<target name="manifest">
        <fileset id="sources" dir="${libraryFolder}">
                <include name="**/*.as"/>
        </fileset>
        <pathconvert property="classes" pathsep=" " refid="sources">
                <chainedmapper>
                        <globmapper from="${basedir}/${libraryFolder}/*" to="*"/>
                        <mapper type="package" from="*.as" to="*"/>
                </chainedmapper>
        </pathconvert>
        <echo message="manifest = ${classes}"/>
</target>

Here we are generating a string of classes which include their package paths, for example;

org.puremvc.as3.multicore.patterns.facade.Facade

Here you can see the class Facade.as from the PureMVC framework, note that the file extension is omitted. This string should be identical to the one inside the .as file after package with the addition of the class name. Make sure you do not start the string with lib.puremvc.as3… as this will not compile due to the fact that the sting does not match what is written in the class file itself.

Exclude the classes in the manifest

This is a simple task with one catch. Firstly the argument to the asdocs tool which excludes classes from compilation looks like this.

<arg line="-exclude-classes ${classes}"/>

This argument uses the ‘classes’ property which is generated by the manifest target as the list of classes to exclude. The catch is that you have to set the ‘-source-path’ of asdocs to your lib folder otherwise asdoc will not be able to locate the source files.

<arg line="-source-path ‘${basedir}/lib’"/>

Add swc locations to asdoc with ‘+=’

I encountered trouble with asdoc losing its default reference to the flex SDK when i assigned external libraries without the += syntax, particularly when i was experimenting with the compc tool. Just remember that you must specify the locations of all swc files used by your source and the source in your library. This should be done in this manner.

<arg line="-external-library-path+=swc"/>

Here i am specify in the folder named ’swc’ in my base directory.

Use ‘-lenient’ compilation

In SDK 4.x asdoc supports the ‘-lenient’ tag, this tells asdocs to ignore badly formatted HTML, i found this to be a very useful addition. An error log is created when errors are encountered so you can fix them should you choose to, asdocs will tell you the location.

<arg line="-lenient"/>

Set asdocs ‘-doc-classes’ to the main file

The slightly ambiguous ‘-doc-classes’ tag is the tag you should use to generate documentation for all the classes used in your project. You only have to specify one class and asdocs will trawl through the project hierarchy from here documenting the classes you have used and ignoring those you have not. If you are using asdocs to write documentation for an application just point the ‘-doc-classes’ to the ‘Main.as’ file in your src folder. Otherwise if you are compiling a library of your work you have the option of listing the files you want to be compiled and using the ‘-doc-classes’ tag or simply using pointing ‘-doc-sources’ at the location of your “would be” library. Either way it is important to point ‘-source-path’ to your src folder just as we did fr the lib folder, again this is important as it matches the physical locations of source files to the locations they define in their package deceleration. My asdoc target looks like this,

<target name="asdocme">
        <exec executable="${bin.dir}/asdoc" failonerror="true">
                <arg line="-source-path ‘${basedir}/src’ ‘${basedir}/${libraryFolder}’"/>
                <arg line="-doc-classes ‘${mainFileName}’ "/>
                <arg line="-external-library-path+=lib"/>
                <arg line="-external-library-path+=lib/swc"/>
                <arg line="-external-library-path+=swc"/>
                <arg line="-exclude-classes ${classes}"/>
                <arg line="-lenient"/>
                <arg line="-main-title ‘ASDocs loves socks’"/>
                <arg line="-window-title ‘ASDocs Window’"/>
                <arg line="-output ‘${Output.dir}’"/>
        </exec>
</target>

Here is a working buildfile for the last project i used this method on, to use it you should only have to set the properties at the top of the file and change the locations of the swc library folders in the asdoc target to be relavent to your project.

<project name="AsDocTest" default="main" basedir=".">
        <!– location of FlexSDK –>
        <property name="FlexSDK.dir" location="/Applications/Adobe Flex Builder 3/sdks/4.0.0.6449"/>   
        <!– location of ASDocs folder–>
        <property name="bin.dir" location="${FlexSDK.dir}/bin"/>       
        <!–no spaces in output folder name CHOOSE NEW FOLDER OR FILES WILL BE OVERWRITEN–>
        <property name="Output.dir" location="${basedir}/asdocs"/>

       
        <!–Main file, this will become the root from which asdocs searches for files
                , dont type the fileextension (.as or .mxml)–>

        <property name="mainFileName" value="Main"/>
        <!–the location of the lib folder relative to the project directory–>
        <property name="libraryFolder" value="lib"/>
        <!–paths to folder containing swc used in the project, again relative to the project directory–>
        <property name="swcLibraryPaths" value="’${basedir}/lib’ ‘${basedir}/lib/swc’ ‘${basedir}/swc’"/>
       
       
        <!– Main –>
        <target name="main" depends="clean,manifest,asdocme" description="full build of asdocs"/>
       
        <!–Deletes the output dir if it already exists and then creates a new one–>
        <target name="clean">
                <delete dir="${Output.dir}" failOnError="false" includeEmptyDirs="true"/>
                <mkdir dir="${Output.dir}"/>
        </target>
       
        <!–
        Creates a manifest of the lib file, all files found in theis dir are to be excuded from the asdocs             
        –>

        <target name="manifest">
                <fileset id="sources" dir="${libraryFolder}">
                        <include name="**/*.as"/>
                </fileset>
                <pathconvert property="classes" pathsep=" " refid="sources">
                        <chainedmapper>
                                <globmapper from="${basedir}/${libraryFolder}/*" to="*"/>
                                <mapper type="package" from="*.as" to="*"/>
                        </chainedmapper>
                </pathconvert>
                <echo message="manifest = ${classes}"/>
        </target>

        <target name="asdocme">
                <exec executable="${bin.dir}/asdoc" failonerror="true">
                        <arg line="-source-path ‘${basedir}/src’ ‘${basedir}/${libraryFolder}’"/>
                        <arg line="-doc-classes ‘${mainFileName}’ "/>
                        <arg line="-external-library-path+=lib"/>
                        <arg line="-external-library-path+=lib/swc"/>
                        <arg line="-external-library-path+=swc"/>
                        <arg line="-exclude-classes ${classes}"/>
                        <arg line="-lenient"/>
                        <arg line="-main-title ‘ASDocs loves socks’"/>
                        <arg line="-window-title ‘ASDocs Window’"/>
                        <arg line="-output ‘${Output.dir}’"/>
                </exec>
        </target>
</project>

Project Manager Opening

We are looking for an experienced PM to join our small and friendly team of eleven, in our handsome studio in Shoreditch.

You can find more information and a detailed job spec here

Emak Mafu supporting London Digital Week

Emak Mafu are proud to be supporting London Digital Week 09, the first year of the event. It will mean that every year London will become the center of the digital world, keep your diaries free from September 21-28!

London Digital Week Logo

What Adobe Groups should be…

I’m not going to go into too much detail about Adobe Groups, but I have a few main gripes with it:

Firstly, it lacks many of the features that other sites like meetup.com offer. To try and match them for features is commercial suicide. They manage those platforms full time and have the right talent in-house, and for Adobe to dedicate time and money to try and match them seems insane.

Secondly, how are we supposed to transfer all our users to a platform that is buggy and feature poor? We have almost 1000 members on our meetup site, they won’t all migrate.

Thirdly, user groups are meant to be independent of Adobe. We are all grown up enough to be able to find a platform that suits our needs. Do independent groups really want to host all their data on Adobe servers?

So, I don’t think it’s fair to have a go at Groups without coming up with an alternative. What do we need instead? I mocked this up in 2 minutes with Balsamiq.

The functionality goes something like this:

User enters location
Google maps zooms in
User checks the checkboxes of the technologies/apps they are interested in
Groups pop up on the map
User slides the “distance” slider to set how far they would travel (eg. 2km, 10km, 50km etc.)
Groups appear/disappear as this is increased/decreased

Please Adobe, listen to feedback and make things simple! There was no need for Groups, all we need is a very good listing application!

adobegroups

We have a new blog

Well after the tears - the blood and the sweat - we have a new blog up. Which you already know as you’re looking at this.

More exciting news to come.

Flash Camp London!

In case you didn’t already know, Emak Mafu are helping organise Flash Camp in London. Please go to the flashcamp website. Speakers include:

Mike Chambers, Adobe
Lee Brimelow, Adobe
Serge Jespers, Adobe
Seb Lee Delisle, Plug-in Media
James Whittaker, RefreshingApps
Richard Dean, Lightmaker
Michael Chase, AKQA

It’s a free half day event, we can’t wait!

swfaddress firefox 3 fix

Hey

Since the release of firefox 3, some of our sites have been a little temperamental as we use swfaddress heavily in our production. This blog seems to be the place to solve this problem, but i had to fafe about getting the uncompressed version in order to add the code - thought i would post the amended code: [download#1#nohits]

i haven’t had time to compress it again - definitely needed as without javascript compression it doubles in size

Recruiting Developers in London

Thought I would share this list that we have compiled of good places to post if you are looking for developers in London:

jobsite.co.uk - £299 (+vat) / 2 weeks
cwjobs.com - £195
reed.co.uk - £50 (+vat)
creativepool.co.uk - £220 / 28 days
actionscript.org - $150 / 2 weeks (for freelancers)
thefwa.com - £58.75 / 30 days
krop.com - $200 / 30 days
theitjobboard.co.uk - £550
london.digital-jobs.org/ - Free

Let me know if you find any more!

FOWA Expo

I’m at FOWA today courtesy of Adobe. Still not really sure what to think. I came with a hope of meeting some developers, ended up meeting some old friends and making some new contacts. Just sat through a talk about Cappuccino, talking about Object-J etc. Nice stuff and it’ll be interesting to see how it will run, but I don’t think it’s for us. There’s a big presence from Micro$oft, still flogging Shilvershite. Saw their “table”, which is basically a big iPhone. And please Carson, take your hat off indoors, you look like a plonker!

sync your mobile with google calendar

Hey,

Here at emakmafu we abuse google apps to the max - they are an integral part of our administration. One thing I have been longing for for ages is a way to have my mobile hook up with google calendar and do a two way sync. I had a look about a year ago when i got my nokia n95, and the only solution was to sysnc with ical, then ical to google, (ball-ache!) so i dropped that, as that’s just adding a whole new calendar to the problem… I just checked again, and discovered www.goosync.com. Its a two tier service, basic calendar syncing is free, with the option to upgrade to take care of syncing contact and tasks, autosync + loads more.

I was up and running within 5 minutes! well chuffed! (iphone compatible too!)