So you have a lot of packages and you want to add description for all your package for ASDoc? You can use the -packages.package parameter but it can be tedious to repeat the ASDoc command line parameter (-packages.package) for each individual package.
Now you don’t have to repeat the parameter because you can now use the new parameter (-package-description-file) instead.
Using the new parameter (-package-description-file) you can now specify a xml file that contains the description for all your packages.
The format of the file is as follows:
<overviews> <packages> <package name="package.name1"> <shortDescription></shortDescription> <description></description> </package> </packages> </overviews>
Here is a sample file (pkgDescription.xml)
<overviews> <packages> <package name="mx.core"> <shortDescription> <![CDATA[ The mx.core package contains the base classes and interfaces, such as UIComponent, used by Flex. ]]> </shortDescription> <description> <![CDATA[ The mx.core package contains the base classes and interfaces, such as UIComponent, used by Flex. ]]> </description> </package> <package name="mx.controls"> <shortDescription> <![CDATA[ The mx.controls package contains the Flex user-interface controls. ]]> </shortDescription> <description> <![CDATA[ The mx.controls package contains the Flex user-interface controls. ]]> </description> </package> </packages> </overviews>
Here is how you can use it:
./asdoc -package-description-file=pkgDescription.xml -doc-classes=mx.controls.Button -source-path=<sdk root>/frameworks/projects/framework/src
This parameter is available in Flex SDK 4 only. And the nightly build of Flex SDK 4 can be found at http://opensource.adobe.com/wiki/display/flexsdk/Download+Flex+4 (choose a build after 4.0.0.8245 to use this parameter)
I tried using it and it seems like it strips out any html tags. I had in the full description a list of links inside of a CDATA tag. But after running ASDoc, all that’s left is just the text. Any way around this?
make sure that you replace html chars with entities.
for example < with < and > with >
Hi
We will use Flex in our next project. A number of teams will work separately and run asdoc as part of their build process. After the build, generated documents will be copied to the central repository.
Is there a way to link the documents generated by various teams, so they merge to one convenient package?
If possible, we want to avoid running asdoc again for all classes because the source may not be available and also it might be time consuming.
Thanks in advance!
I did that and it still didn’t come through. I have it encoded into entities in my pkgDescription.xml file. But if i looked at the overviews.xml that is generated, all of my entities are converted back into their normal forms. Then they are ignored again.
No, you can’t combine asdoc.
There is a bug already http://bugs.adobe.com/jira/browse/SDK-18720 for this.
@Gabriel,
I just tried that and it worked for me.
here is what I tried:
<overviews>
<packages>
<package name=”mx.controls”>
<shortDescription>
<![CDATA[
The mx.controls package <b>contains</b>
the Flex user-interface controls.
]]>
</shortDescription>
<description>
<![CDATA[
The mx.controls package <b>contains</b>
the Flex user-interface controls.
]]>
</description>
</package>
</packages>
</overviews>
notice <b>contains</b>
Thanks for the reply.
So, moving source code from all projects to a central repository and then running asdoc again seems to be the only option.
Is that correct? (just to confirm)
—-
Gaurav says:
July 8, 2009 at 4:12 PM
No, you can’t combine asdoc.
There is a bug already http://bugs.adobe.com/jira/browse/SDK-18720 for this.
@G,
Yes, that correct.
That resolved my issue. I had CDATA with unencoded tags, then I had no CDATA but encoded tags. I didn’t try CDATA AND encoded tags. Thanks!
This is very helpful for me, still i a have difficulty how to mention the default package in the packageDocs.xml file. i tried with “.”, “/” etc.