ASDoc Enhancements

Wed, 01/28/2009 - 17:18 — Boris
Box2DBox2D

I've not posted for a while, but that doesn't mean I've not been doing anything. Generally less visible stuff (yes, some porting), but I have converted Box2DFlashAS3 to use ASDoc to generate beautiful documentation.
The results are available here. For lack of a better place, this will be their permanent home, and I'll try to keep them updated to the latest revision.

I've put in a few customizations to the standard ASDoc template, that I'm going to share here, as they are generally useful. You will need to customize the files a bit for your own project, though.

Usage

Examples of hidden features

The files contains an example of adding an appendix, and hiding internal namespaces, in the file ASDoc_Config_Base.xml. These features were already available, but it is not well demonstrated how to use them.

@warning tag

You can now mark any documenting code block with the @warning tag to emit a warning in the description. Example

Source reference

If you specify a location in ASDoc_Config_Base.xml, then all classes will provide a source link to the file they were generated from. If you need finer control (e.g. per-package destinations), let me know.

Smart sort order

This ones kinda specific to Box2D, but I left it in in case anyone else can find a use for it. The index of all identifiers ignores the "b2" that all Box2D classes start with when it comes to sort order. e.g. b2AABB can be found under "A", not "B".

Dotfile generation

As well as generating HTML output, a "class.dot" file will be generated which is a valid GraphViz dot file. This allows you to generate class inheritance diagrams, though I haven't implemented automatically generating it and inserting it into the HTML documentation. Inheritance is shown by an ordinary arrow, and interfaces with dotted lines.

Installation

Download the following zip, and use the files inside to replace the ones found in (a copy of) your %FLEX_HOME%\asdoc\templates folder. Then ensure you call ASDoc using the -templates-path switch, if you've used some other folder.

AttachmentSize
New template files23.8 KB

Hi, Borris Appreciated your

Hi, Borris

Appreciated your documentation. It is great. I have a question: I use Flash CS3, and need to access your documentation from my local computer. I downloaded the above template files, but can't see any description. Is there any zip version of your documentation.

Sincerely,

This package is really for

This package is really for people wanting fancier ASDoc for their own projects. The Box2D SVN contains a local version ready set up to generate docs. Plus, later releases will no doubt come with it.

Proper Internal Namespace Exclusion?

I was a little disappointed when I tried out your template after reading that you had managed to hide the internal namespace. You aren't hiding the internal namespace at all, you are simply hiding a custom namespace that happens to be declared as internal - big difference. It seems as though ASDoc treats everything in the internal namespace as public and as far as I can tell there is nothing that can be changed in the XLS files to prevent that.

Nice work on the appendixes section though, that will no doubt come in useful. :-)

Proper Internal Namespace Exclusion?

Sorry, I should have been more specific. The namespace I'm hiding is "b2internal". Have you tried putting in "internal" instead? If it really is that annoying, then I've got no better work around than adding tons of @private tags.

Reply to comment | www.boristhebrave.com

Microdermabrasion's genius is its simplicity. It doesn't require the use of lasers, harsh chemicals or
any invasive technologies. Alternatively, a pressurised jet of tiny zinc
or aluminium oxide crystals are directed across the
surface on the skin.

One of the most asked

One of the most asked questions by migrants is "How do I choose a school for my children? ". This article looks at some of the things you can do to help make that task a little easier. The article offers advice and websites for you to carry out your own research. www.punditschool.net


In trying to decide what type of college will best meet your wants and needs there are many things to consider. Listed below are some of the factors you will need to consider in deciding where you want to go to college. www.choicecollegeconsulting.net


Beauty is the source of your personal magic; it is the essence of who you are, it connects you to others and to the plenty of this planet. www.thebeautybox.net


We have separated children's sun protection into two categories. 1. Babies and Sun Protection and 2. Kids and Sun Protection.... I guess there should be a third category for teenagers but as they say, "Cats have nine lives. www.sunvalleyautocare.net


An Enterprise Service Bus (ESB) is a flexible connectivity infrastructure for integrating applications and services. The Enterprise Service Bus(ESB) can help you achieve the goal of SOA. www.icounselingservices.net


Whether you are looking for a service provider in household energy, telecommunication, banking and finance, insurance, travel, technology or even shopping, you deserve nothing but the very best as a customer. www.intoservices.net


Do you ever worry that your business will fail? It's hard to contemplate failure, especially when you're working so hard and want so much to be successful. www.suisunbusinessnews.net


Some babies are naturally prone to be smart by genetics, while others are less apt to get the 'genius gene'. However, as parents it is our duty to harness the full potential of our children from birth. Here's 20 ways to encourage early learning development for your baby... www.babycase.net


Auto (car) insurance is a type of insurance coverage for damage to and resulting from an auto. Insurance of this type can cover a variety of things depending on the kind of auto insurance that has been purchased. www.autohavenonline.net


The end result is much lower repair bills with a great friendly service. This is the insiders' step by step approach on how best to find the right local auto repairs. www.suppliesauto.net


This is the easiest way of finding the best local garage to use for any auto repairs. The end result is the car is serviced or repaired the way you want it to be done and at prices agreed. www.roadrunnerautomart.net


A sound tech's primary duty is to assist the sound engineer and he has only one major responsibility, which is to be attentive. Here are some specific instructions to become a better sound tech. www.brightontech.net


Sports Betting Champ, John Morrison is most well known for his 97% win rate MLB/NBA sports betting system. But, the Sports Betting Champ has also brought us other valuable products... www.safeguardsports.net


You are a sports fan and your life revolves around your favorite teams and athletes. Decorating a room to show off your team spirit and loyalty is a must. www.fan-sport.net


Looking for the best Christmas gift ideas for the sports fan as the holiday season approaches is a common experience. www.vikingmotorsports.net

Greater Swiss Mountain Dog

Greater Swiss Mountain Dog Training is not that complicated as it sounds. Though it is true that it requires skills and education to teach Swiss Mountain dogs and make them learn, but once you have been trained to train these dogs, things will become much easier. www.mountaindogmission.net


Although the information of its beginning is vague, the origin and historical background of Greater Swiss Mountain dog dates back to first century B. C. There are three stories that are usually told about these dogs' origin. www.topdogpetgrooming.net


Just as people sometimes dread getting old, they also dread their pets getting old. Dogs and cats are living longer than ever and pet owners attribute some of the chronic problems they develop to just getting old. www.doc4pets.net


Before purchasing pet insurance for their pets, there are many factors that pet owners should consider. www.pethealingenergy.net


Failure to do adequate research and fully understand what they are purchasing is the main reason that pet owners have claims denied and/or end up being disappointed with pet insurance. www.mypetfolies.net


Perfect homes are those where you can feel relaxed, calm and comfy. A home of dreams is not easy to achieve. You have to bring your thoughts, ideas and dreams into reality. www.countryhomerealestate.net


In today's tough real estate market, the Internet is playing a huge role in the buying and selling of real estate and is an almost limitless source of real estate information. www.pnsrealestate.net


Finding the right doctor for you and your family is an art in itself. Many people are not sure about how to look for a doctor. Conventionally, doctors are found by word of mouth. www.thefamilylawdoctor.net


The energy sector in Indonesia has struggled to keep up with the rapid pace of economic growth. Chronic under investment in systems improvements and new generation capacity, coupled with highly subsidized fuel and electricity rates, has left Indonesia in a dire situation. www.energylawjournal.net


Most people hate laws since laws always restrict the freedom of human beings. In reality laws are like human beings who can be your friend, enemy, guide and servant. Read this article to know the fundamentals of law. www.olivelawfirm.net


When you imagine a lawyer what do you see? More than likely you conjure up an idea of a powerful looking man or woman in a dark colored suit with a serious expression. www.lawyercards.net


Vanity Laws - the fad of creating laws to honor the memory of someone who has met a tragic end is ushering in a tragic end to democracy. It's time this nonsense was stopped. www.charlescolmanlaw.net


All civilized societies pay lot of emphasis on the rule of law. The developed countries are quite proud of their strict enforcement of law while the poor nations are often ashamed that they can't make their society law compliant. www.markrenkenlaw.net


If you're planning to attend a kid's birthday party, or if Christmas is around the corner, you may need to start thinking about finding the best gifts for kids that are age appropriate. www.healthykidscompany.net


In the last few months there have been many Health Care Reform rules and regulations updated by the Health and Human Services Department. But despite all the media coverage of these events, many people still hold fast to certain myths surrounding ObamaCare. www.luminasanarehealthcenter.net

Post new comment

The content of this field is kept private and will not be shown publicly.
CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.