Thanks.
It looks like MXRoyale/SparkRoyale is causing ASDoc to fail.
I got it compile and work by commenting out all the MX and Spark stuff.
Can someone who’s been working on that, take a look?
How does this actually *work* though?
* It looks like it’s using asdoc.jar to do *something*. What that something is
and how it works, I don’t quite understand.
* The config files have a list of doc-namespaces. What’s the purpose of that?
* There is a list of exclude-sources. Why is that?
* How do we decide what goes into exclude-classes?
* What is the namespaces section used for?
One thing I’d like to fix is that none of the utility functions are appearing
in the ASDocs. Let’s take org.apache.royale.utils.array.rangeCheck for example:
We have the following entry in index.js.json:
{ "name": "rangeCheck",
"type": "Method",
"class": "org.apache.royale.utils.array",
"description": "Checks that an index falls within the allowable range of an
array."},
And we have the following in org.apache.royale.utils.array.rangeCheck.js.json:
{ "type": "method",
"qname": "org.apache.royale.utils.array.rangeCheck",
"namespace": "public",
"bindable": [],
"details": [],
"deprecated": {},
"description": "Checks that an index falls within the allowable range of an
array. Returns true if it's valid, false if not.",
"tags": [
{ "tagName": "playerversion",
"values": ["Flash 10.2", "AIR 2.6"]},
{ "tagName": "productversion",
"values": ["Royale 0.9"]},
{ "tagName": "langversion",
"values": ["3.0"]},
{ "tagName": "royalesuppressexport",
"values": []} ],
"return": "Boolean",
"params": [{ "name": "index", "type": "int"},
{ "name": "arr", "type": "Array"}]}
But there’s no reference anywhere else and it’s not actually a method of a
class.
Where would I look to try and fix this?
Also, there’s no docs for XML/XMLList. I see the following in the config files:
<!-- leave out XML. In the SWF compile it confuses the compiler
because
airglobal.swc also has an XML definition
<path-element>${frameworks_dir}/projects/XML/src/main/royale</path-element> -->
I’m curious if there’s some way around this. Maybe even to hard-code XML docs?
Harbs
> On Nov 29, 2021, at 9:22 AM, Alex Harui <[email protected]> wrote:
>
> IIRC, the "asdoc" target in the top-level build.xml does not work and is kept
> around in case we try to make it work the way Flex did.
>
> Flex ASDoc used DITA and XSLT which I did not want to learn and figured most
> others didn't want to learn either, so I put together examples/royale/ASDoc.
> Make sure you run the "clean" target otherwise it might not rebuild the
> "json" target which asks the Royale compiler to generate JSON from the ASDoc
> encountered while compiling the SWCs.
>
> Looks like the Jenkins server hasn't built ASDoc in a long time because it
> was configured to be triggered by a build from another committer's Jenkins
> server which we never got working. But the build currently fails locally as
> happens from time to time probably from unexpected or improperly formatted
> ASDoc comments. Wade through the output, find the problem comments and
> either fix the compiler or adjust the comments.
>
> The net result is a Royale app for Royale documentation, showcasing what
> Royale can do.
>
> FWIW, I also put together examples/royale/RoyaleWebsite. It might be worth
> considering again. Past discussion concluded that Royale was more for
> webapps than websites, but it might be worth leaving behind WP and the custom
> theme and proving that either Royale can be the base for a site or that
> Royale integrates well into a standard website. Maybe abandon that example
> as well and rebuild the site out of some popular non-WP thing (GH Pages?) and
> plug Royale applets into the html files to showcase a weather reporter or for
> the contactUs form.
>
> HTH,
> -Alex
>
> On 11/28/21, 8:26 AM, "Yishay Weiss" <[email protected]> wrote:
>
> Unfortunately it isn’t building now [1] (last successful build was a year
> and a half ago). I may be looking at the wrong thing because part of 0.9.8
> release was to check ASDocs so it would have passed then…
>
> [1] Royale_ASDoc_Example #956 Console [Jenkins]
> (azure.com)<https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fapacheroyaleci2.westus2.cloudapp.azure.com%3A8080%2Fjob%2FRoyale_ASDoc_Example%2F956%2FconsoleFull&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=dFFYN%2Fp7hUDJ%2B8rEIg%2BrrtI6TFlj%2BE4JLZz9qHi2q1g%3D&reserved=0>
>
> From: Yishay Weiss<mailto:[email protected]>
> Sent: Sunday, November 28, 2021 6:06 PM
> To: [email protected]<mailto:[email protected]>
> Subject: RE: ASDoc
>
> I see the following file being used
>
> examples/royale/ASDoc/build.xml
>
> From: Yishay Weiss<mailto:[email protected]>
> Sent: Sunday, November 28, 2021 6:00 PM
> To: [email protected]<mailto:[email protected]>
> Subject: RE: ASDoc
>
> It’s built in CI server so I can have a look there at the config later if
> nobody else beats me to it.
>
> From: Harbs<mailto:[email protected]>
> Sent: Sunday, November 28, 2021 3:51 PM
> To: [email protected]<mailto:[email protected]>
> Subject: Re: ASDoc
>
> I managed to generate compiler-royaleTasks.jar and I tried copying that
> manually and renaming it to royaleTasks.jar, but that didn’t help.
>
> I’m groping in the dark here…
>
> I think I’m going to have to wait for Alex...
>
>> On Nov 28, 2021, at 3:33 PM, Harbs <[email protected]> wrote:
>>
>> It’s defined in the top level here:
>>
>> <target name="load-task" depends="runtime-setup">
>> <!-- load the <mxmlc> task; we can't do this at the <project> level
>> -->
>> <!-- because targets that run before flexTasks.jar gets built would
>> fail -->
>> <taskdef resource="flexTasks.tasks"
>> classpath="${basedir}/js/lib/compiler-royaleTasks.jar"/>
>> </target>
>>
>>
>> and in asdocs here:
>>
>> <path id="flexTasks.path">
>> <fileset dir="${ROYALE_HOME}">
>> <include name="lib/royaleTasks.jar" />
>> <include name="ant/lib/royaleTasks.jar" />
>> </fileset>
>> </path>
>> <taskdef resource="flexTasks.tasks" classpathref="flexTasks.path"/>
>>
>> but for some reason flexTasks.path has no value.
>>
>> well, maybe it’s because royaleTasks.jar does not exist…
>>
>> I’ll have to see if I can figure out what creates that.
>>
>>> On Nov 28, 2021, at 3:26 PM, Andrew Wetmore <[email protected]
>>> <mailto:[email protected]>> wrote:
>>>
>>> We have a resource file called flexTasks? Or did it get renamed to
>>> something like royaleTasks and the script was not updated?
>>>
>>> On Sun, Nov 28, 2021 at 9:10 AM Harbs <[email protected]
>>> <mailto:[email protected]>> wrote:
>>>
>>>> Yeah…
>>>>
>>>> Harbss-Mac-mini:royale-asjs harbs$ ant asdoc
>>>> Buildfile: /Apache/royale-asjs/build.xml
>>>>
>>>> asdoc:
>>>> [echo] ROYALE_HOME = /Apache/royale-asjs
>>>> [echo] royalelib = /Apache/royale-asjs/frameworks
>>>> [echo] doc_output = /Apache/royale-asjs/asdoc-output
>>>> [echo] compiler.source-path =
>>>> /Apache/royale-asjs/frameworks/projects/*/src/main/royale
>>>>
>>>> clean:
>>>>
>>>> doc:
>>>> [taskdef] Could not load definitions from resource flexTasks.tasks. It
>>>> could not be found.
>>>>
>>>> BUILD FAILED
>>>> /Apache/royale-asjs/build.xml:815: The following error occurred while
>>>> executing this line:
>>>> /Apache/royale-asjs/asdoc/build.xml:73: Problem: failed to create task or
>>>> type asdoc
>>>> Cause: The name is undefined.
>>>> Action: Check the spelling.
>>>> Action: Check that any custom tasks/types have been declared.
>>>> Action: Check that any <presetdef>/<macrodef> declarations have taken
>>>> place.
>>>>
>>>>> On Nov 28, 2021, at 2:29 PM, Andrew Wetmore <[email protected]
>>>>> <mailto:[email protected]>> wrote:
>>>>>
>>>>> I see the build script here [1]. I presume you update the ASDoc files and
>>>>> then run this script. HOW you run this script, I do not know.
>>>>>
>>>>> a
>>>>>
>>>>> [1]
>>>>> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Froyale-asjs%2Fblob%2Fdevelop%2Fasdoc%2Fbuild.xml&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=W9TSqepRR6ilfxBZ%2B%2FBDnYAPew3V5bF0I4rgX4IJx%2BA%3D&reserved=0
>>>>>
>>>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Froyale-asjs%2Fblob%2Fdevelop%2Fasdoc%2Fbuild.xml&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=W9TSqepRR6ilfxBZ%2B%2FBDnYAPew3V5bF0I4rgX4IJx%2BA%3D&reserved=0>
>>>>>
>>>>> On Sun, Nov 28, 2021 at 5:47 AM Harbs <[email protected]
>>>>> <mailto:[email protected]>> wrote:
>>>>>
>>>>>> I don’t see any docs on the docs… ;-)
>>>>>>
>>>>>> I’d really like to work on this, but I’m not sure where to start.
>>>>>>
>>>>>>> On Nov 15, 2021, at 4:03 PM, Andrew Wetmore <[email protected]
>>>>>>> <mailto:[email protected]>>
>>>> wrote:
>>>>>>>
>>>>>>> I think there is some, um, documentation on building ASDoc on the
>>>> wiki. I
>>>>>>> will go look.
>>>>>>>
>>>>>>> a
>>>>>>>
>>>>>>> On Mon, Nov 15, 2021 at 8:59 AM Harbs <[email protected]
>>>>>>> <mailto:[email protected]>> wrote:
>>>>>>>
>>>>>>>> I’m interested in improving the ASDoc app and info.
>>>>>>>>
>>>>>>>> Some things I’m interested in (besides improving the look) is:
>>>>>>>> 1. Adding utility functions. Those seem to be missing.
>>>>>>>> 2. Release versioning.
>>>>>>>> 3. Add some top level info like XML.
>>>>>>>>
>>>>>>>> Who understands how ASDoc builds work?
>>>>>>>>
>>>>>>>> Thanks,
>>>>>>>> Harbs
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Andrew Wetmore
>>>>>>>
>>>>>>> https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.blogspot.com%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=MUSyxyv4QY7s2yc5H16cMJyWqb6q%2BOG7SyoNZb%2BJstw%3D&reserved=0
>>>>>>>
>>>>>>> <https://nam04.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.blogspot.com%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=MUSyxyv4QY7s2yc5H16cMJyWqb6q%2BOG7SyoNZb%2BJstw%3D&reserved=0>
>>>>>>
>>>>>>
>>>>>
>>>>> --
>>>>> Andrew Wetmore
>>>>>
>>>>> Editor, Moose House Publications
>>>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmoosehousepress.com%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=5bfdrv4AYi2azY6yXwmjKHUNE%2FpqDINBW0a%2F3QgR8i4%3D&reserved=0
>>>>>
>>>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmoosehousepress.com%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=5bfdrv4AYi2azY6yXwmjKHUNE%2FpqDINBW0a%2F3QgR8i4%3D&reserved=0>>
>>>>> Editor-Writer, The Apache Software Foundation
>>>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fapache.org%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=k28Pzhc0q%2BRVnNFE60yqXkgf9C5k72exGmumr%2FK6sAY%3D&reserved=0
>>>>>
>>>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fapache.org%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=k28Pzhc0q%2BRVnNFE60yqXkgf9C5k72exGmumr%2FK6sAY%3D&reserved=0>>
>>>>
>>>>
>>>
>>> --
>>> Andrew Wetmore
>>>
>>> Editor, Moose House Publications
>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmoosehousepress.com%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866922696%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=5bfdrv4AYi2azY6yXwmjKHUNE%2FpqDINBW0a%2F3QgR8i4%3D&reserved=0
>>>
>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmoosehousepress.com%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866932653%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=NHQOQk0LAGF4CxckjcJZo0YcwZoZuCjimexTbPiuvfs%3D&reserved=0>>
>>> Editor-Writer, The Apache Software Foundation
>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fapache.org%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866932653%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=iPdJslIrwml2R23603xVGzOil5lbusceyJ9Pum%2Biz30%3D&reserved=0
>>>
>>> <https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fapache.org%2F&data=04%7C01%7Caharui%40adobe.com%7C766e6d97e81242f67ec508d9b28b9dc8%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C637737135866932653%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=iPdJslIrwml2R23603xVGzOil5lbusceyJ9Pum%2Biz30%3D&reserved=0>>
>>
>
>
