From kremens at gmail.com  Thu Sep  1 13:51:19 2005
From: kremens at gmail.com (Jim Kremens)
Date: Thu Sep  1 13:51:29 2005
Subject: [as2api-dev] error: No packages specified
Message-ID: <ccedf66c050901065142750066@mail.gmail.com>

Hi all,

I'm trying to use Ant to call as2api.  I have the following:

<target name="document">
	<exec executable="${as2api}" failonerror="false">
		<arg line='--classpath "${dist}"'/>
	</exec>
</target>

This task successfully calls as2api, and I think it passes it the
right path for '--classpath'.  But it seems to be looking for a
'<package spec>'.

What's a '<package spec>' and how can I pass one to as2api?

I'm using Eclipse and FDT.  

Thanks,

Jim Kremens

From dave at badgers-in-foil.co.uk  Thu Sep  1 14:24:21 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Thu Sep  1 14:24:24 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <ccedf66c050901065142750066@mail.gmail.com>
References: <ccedf66c050901065142750066@mail.gmail.com>
Message-ID: <20050901142421.GB27516@badgers-in-foil.co.uk>

On Thu, Sep 01, 2005 at 09:51:19AM -0400, Jim Kremens wrote:
> I'm trying to use Ant to call as2api.  I have the following:
> 
> <target name="document">
> 	<exec executable="${as2api}" failonerror="false">
> 		<arg line='--classpath "${dist}"'/>
> 	</exec>
> </target>
> 
> This task successfully calls as2api, and I think it passes it the
> right path for '--classpath'.  But it seems to be looking for a
> '<package spec>'.
> 
> What's a '<package spec>' and how can I pass one to as2api?

You need to tell as2api which packages are being documented, either by
naming the packages explicitly:

  com.example.foo

or by giving the prefix shared by all packages to be documented:

  com.example.*


So, you'll need to add something like this to the <exec>:

  <arg line='com.example.*'/>


[I was working on an HTML version of the documentation when my laptop
died a few days back.  Here's the relevant section:

  http://www.badgers-in-foil.co.uk/projects/as2api/as2api-documentation.html#options

Note that this documents some options which were not yet implemented in
the last (0.3) release.]


hope that helps,
dave

-- 
http://david.holroyd.me.uk/

From xavi at code4net.com  Thu Sep  1 14:35:24 2005
From: xavi at code4net.com (Xavi Beumala)
Date: Thu Sep  1 14:35:35 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
Message-ID: <431711AC.3050602@code4net.com>

Hi all,
I'm having problems when documenting a getter/setter property wich has  
a [Inspectable] meta tag associated:

<code>
/**
* Getter/Setter
*/
public function get myVar():String {
  return _myVar;
}

public function set myVar(mr:String) {
 _myVar = m;
}
</code>

The code above generates correctly the documentation for the class, but 
if the code changes to:

<code>
[Inspectable]
/**
* Getter/Setter
*/
public function get myVar():String {
  return _myVar;
}

public function set myVar(mr:String) {
 _myVar = m;
}
</code>

Then as2api doesn't add the comments to the documentation.

I'm missing something?

Thanks in advance
Xavi Beumala

From kremens at gmail.com  Thu Sep  1 15:31:48 2005
From: kremens at gmail.com (Jim Kremens)
Date: Thu Sep  1 15:31:56 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <20050901142421.GB27516@badgers-in-foil.co.uk>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
Message-ID: <ccedf66c05090108316a711ed1@mail.gmail.com>

Thanks!

What if I have one source folder with .com and .org in it?  I pass
as2api the source folder, but how do I pass multiple packages?

Thanks,

Jim Kremens

On 9/1/05, David Holroyd <dave@badgers-in-foil.co.uk> wrote:
> On Thu, Sep 01, 2005 at 09:51:19AM -0400, Jim Kremens wrote:
> > I'm trying to use Ant to call as2api.  I have the following:
> >
> > <target name="document">
> >       <exec executable="${as2api}" failonerror="false">
> >               <arg line='--classpath "${dist}"'/>
> >       </exec>
> > </target>
> >
> > This task successfully calls as2api, and I think it passes it the
> > right path for '--classpath'.  But it seems to be looking for a
> > '<package spec>'.
> >
> > What's a '<package spec>' and how can I pass one to as2api?
> 
> You need to tell as2api which packages are being documented, either by
> naming the packages explicitly:
> 
>  com.example.foo
> 
> or by giving the prefix shared by all packages to be documented:
> 
>  com.example.*
> 
> 
> So, you'll need to add something like this to the <exec>:
> 
>  <arg line='com.example.*'/>
> 
> 
> [I was working on an HTML version of the documentation when my laptop
> died a few days back.  Here's the relevant section:
> 
>  http://www.badgers-in-foil.co.uk/projects/as2api/as2api-documentation.html#options
> 
> Note that this documents some options which were not yet implemented in
> the last (0.3) release.]
> 
> 
> hope that helps,
> dave
> 
> --
> http://david.holroyd.me.uk/
> 
> _______________________________________________
> as2api-dev mailing list
> as2api-dev@lists.badgers-in-foil.co.uk
> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
>

From dave at badgers-in-foil.co.uk  Thu Sep  1 15:53:53 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Thu Sep  1 15:53:57 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <ccedf66c05090108316a711ed1@mail.gmail.com>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
	<ccedf66c05090108316a711ed1@mail.gmail.com>
Message-ID: <20050901155353.GC27516@badgers-in-foil.co.uk>

On Thu, Sep 01, 2005 at 11:31:48AM -0400, Jim Kremens wrote:
> Thanks!
> 
> What if I have one source folder with .com and .org in it?  I pass
> as2api the source folder, but how do I pass multiple packages?

Sorry; I didn't explain that you can give multiple <package spec>
arguments, so you should be able to have something like:

  <target name="document">
      <exec executable="${as2api}" failonerror="false">
          <arg line='--classpath "${dist}"'/>
          <arg line='com.example.myapp.*'/>  <!-- all 'myapp' packages -->
          <arg line='org.example.utils'/>
          <arg line='net.example.foobar.net'/>
          <arg line='net.example.foobar.io'/>
      </exec>
  </target>



dave

-- 
http://david.holroyd.me.uk/

From kremens at gmail.com  Thu Sep  1 22:38:40 2005
From: kremens at gmail.com (Jim Kremens)
Date: Thu Sep  1 22:38:51 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <20050901155353.GC27516@badgers-in-foil.co.uk>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
	<ccedf66c05090108316a711ed1@mail.gmail.com>
	<20050901155353.GC27516@badgers-in-foil.co.uk>
Message-ID: <ccedf66c0509011538591ca692@mail.gmail.com>

Will multiple lines also work for multiple classpaths?  Or should I
delimit them with a semicolon per the docs?

Also, is it possible to apply different css styles to the docs?

Thanks,

Jim Kremens

On 9/1/05, David Holroyd <dave@badgers-in-foil.co.uk> wrote:
> On Thu, Sep 01, 2005 at 11:31:48AM -0400, Jim Kremens wrote:
> > Thanks!
> >
> > What if I have one source folder with .com and .org in it?  I pass
> > as2api the source folder, but how do I pass multiple packages?
> 
> Sorry; I didn't explain that you can give multiple <package spec>
> arguments, so you should be able to have something like:
> 
>  <target name="document">
>      <exec executable="${as2api}" failonerror="false">
>          <arg line='--classpath "${dist}"'/>
>          <arg line='com.example.myapp.*'/>  <!-- all 'myapp' packages -->
>          <arg line='org.example.utils'/>
>          <arg line='net.example.foobar.net'/>
>          <arg line='net.example.foobar.io'/>
>      </exec>
>  </target>
> 
> 
> 
> dave
> 
> --
> http://david.holroyd.me.uk/
> 
> _______________________________________________
> as2api-dev mailing list
> as2api-dev@lists.badgers-in-foil.co.uk
> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
>

From kremens at gmail.com  Fri Sep  2 04:20:46 2005
From: kremens at gmail.com (Jim Kremens)
Date: Fri Sep  2 04:21:30 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <ccedf66c0509011538591ca692@mail.gmail.com>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
	<ccedf66c05090108316a711ed1@mail.gmail.com>
	<20050901155353.GC27516@badgers-in-foil.co.uk>
	<ccedf66c0509011538591ca692@mail.gmail.com>
Message-ID: <ccedf66c050901212069b8cbfe@mail.gmail.com>

Hi again David,

Sorry to bug you.  I think I'm doing everything right at this point,
but I'm still finding some issues.  as2api seems to overlook some of
the files in a given package.

For example, a package might have 7 classes in it, all inheriting from
the same parent, and the documentation will only show 4.  Can you
think of any reasons for this?

I'd be happy to zip up the files for you if you're willing to test
them.  Perhaps I've found a bug?

Thanks,

Jim Kremens

On 9/1/05, Jim Kremens <kremens@gmail.com> wrote:
> Will multiple lines also work for multiple classpaths?  Or should I
> delimit them with a semicolon per the docs?
> 
> Also, is it possible to apply different css styles to the docs?
> 
> Thanks,
> 
> Jim Kremens
> 
> On 9/1/05, David Holroyd <dave@badgers-in-foil.co.uk> wrote:
> > On Thu, Sep 01, 2005 at 11:31:48AM -0400, Jim Kremens wrote:
> > > Thanks!
> > >
> > > What if I have one source folder with .com and .org in it?  I pass
> > > as2api the source folder, but how do I pass multiple packages?
> >
> > Sorry; I didn't explain that you can give multiple <package spec>
> > arguments, so you should be able to have something like:
> >
> >  <target name="document">
> >      <exec executable="${as2api}" failonerror="false">
> >          <arg line='--classpath "${dist}"'/>
> >          <arg line='com.example.myapp.*'/>  <!-- all 'myapp' packages -->
> >          <arg line='org.example.utils'/>
> >          <arg line='net.example.foobar.net'/>
> >          <arg line='net.example.foobar.io'/>
> >      </exec>
> >  </target>
> >
> >
> >
> > dave
> >
> > --
> > http://david.holroyd.me.uk/
> >
> > _______________________________________________
> > as2api-dev mailing list
> > as2api-dev@lists.badgers-in-foil.co.uk
> > http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
> >
>

From dave at badgers-in-foil.co.uk  Fri Sep  2 08:52:04 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Fri Sep  2 08:52:10 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
In-Reply-To: <431711AC.3050602@code4net.com>
References: <431711AC.3050602@code4net.com>
Message-ID: <20050902085203.GA8939@badgers-in-foil.co.uk>

On Thu, Sep 01, 2005 at 04:35:24PM +0200, Xavi Beumala wrote:
> Hi all,
> I'm having problems when documenting a getter/setter property wich has  
> a [Inspectable] meta tag associated:
> 
> <code>
> /**
> * Getter/Setter
> */
> public function get myVar():String {
>  return _myVar;
> }
> 
> public function set myVar(mr:String) {
> _myVar = m;
> }
> </code>
> 
> The code above generates correctly the documentation for the class, but 
> if the code changes to:
> 
> <code>
> [Inspectable]
> /**
> * Getter/Setter
> */
> public function get myVar():String {
>  return _myVar;
> }
> 
> public function set myVar(mr:String) {
> _myVar = m;
> }
> </code>
> 
> Then as2api doesn't add the comments to the documentation.
> 
> I'm missing something?

I think there is probably a bug.  I've not had the time to investigate
yet -- maybe over the weekend.

I've not done much testing with code which has those attribute tags
unfortunately :(


dave

-- 
http://david.holroyd.me.uk/

From dave at badgers-in-foil.co.uk  Fri Sep  2 09:02:15 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Fri Sep  2 09:02:20 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <ccedf66c0509011538591ca692@mail.gmail.com>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
	<ccedf66c05090108316a711ed1@mail.gmail.com>
	<20050901155353.GC27516@badgers-in-foil.co.uk>
	<ccedf66c0509011538591ca692@mail.gmail.com>
Message-ID: <20050902090215.GB8939@badgers-in-foil.co.uk>

On Thu, Sep 01, 2005 at 06:38:40PM -0400, Jim Kremens wrote:
> Will multiple lines also work for multiple classpaths?  Or should I
> delimit them with a semicolon per the docs?

You can both specify multiple (delimited) arguments to the --classpath
switch, and specify the switch itself multiple times.

Note that you might be able to use Ant's pathref[1] attribute to <arg>
in order to pass in a path defined with a <classpath> elsewhere.  I've
never tried that though.


> Also, is it possible to apply different css styles to the docs?

If you replace the CSS file that as2api gives you by default, yes :)

Note that as2api will not replace an existing stylesheet file (if one
already exists in the target directory) specifically to allow people to
experiment with the formatting.


[1] http://ant.apache.org/manual/using.html#arg


dave

-- 
http://david.holroyd.me.uk/

From dave at badgers-in-foil.co.uk  Sat Sep  3 21:43:44 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Sat Sep  3 21:43:58 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
In-Reply-To: <20050902085203.GA8939@badgers-in-foil.co.uk>
References: <431711AC.3050602@code4net.com>
	<20050902085203.GA8939@badgers-in-foil.co.uk>
Message-ID: <20050903214344.GA32049@badgers-in-foil.co.uk>

On Thu, Sep 01, 2005 at 04:35:24PM +0200, Xavi Beumala wrote:
> I'm having problems when documenting a getter/setter property wich has  
> a [Inspectable] meta tag associated:
> 
> <code>
> /**
> * Getter/Setter
> */
> public function get myVar():String {
>  return _myVar;
> }
> 
> public function set myVar(mr:String) {
> _myVar = m;
> }
> </code>
> 
> The code above generates correctly the documentation for the class, but 
> if the code changes to:
> 
> <code>
> [Inspectable]
> /**
> * Getter/Setter
> */
> public function get myVar():String {
>  return _myVar;
> }
> 
> public function set myVar(mr:String) {
> _myVar = m;
> }
> </code>
> 
> Then as2api doesn't add the comments to the documentation.

I think I've fixed this.  If you're using the Ruby sources, you can
download a modified version of parse/parser.rb from here:

  http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api/parse/parser.rb

Otherwise, let me know what platform you're using, and I'll try to get
an updated executable built for you some time soon.


Thanks for reporting this bug!
dave

-- 
http://david.holroyd.me.uk/

From dave at badgers-in-foil.co.uk  Sat Sep  3 22:12:23 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Sat Sep  3 22:12:26 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <ccedf66c050901212069b8cbfe@mail.gmail.com>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
	<ccedf66c05090108316a711ed1@mail.gmail.com>
	<20050901155353.GC27516@badgers-in-foil.co.uk>
	<ccedf66c0509011538591ca692@mail.gmail.com>
	<ccedf66c050901212069b8cbfe@mail.gmail.com>
Message-ID: <20050903221223.GB32049@badgers-in-foil.co.uk>

On Fri, Sep 02, 2005 at 12:20:46AM -0400, Jim Kremens wrote:
> Sorry to bug you.  I think I'm doing everything right at this point,
> but I'm still finding some issues.  as2api seems to overlook some of
> the files in a given package.
> 
> For example, a package might have 7 classes in it, all inheriting from
> the same parent, and the documentation will only show 4.  Can you
> think of any reasons for this?

Looking at the error messages produced for the problem files, I see that
this sort of syntax is causing the problem,

  private var a, b:String;

The parser as2api uses only expects a single variable to be declared in
such a statement.  I didn't realise that a list of variables was
possible.


Given the usage I can see in your example code, it appears that the
type (String, in the above example) applies to all elements in the list.
I would have thought that it would be possible to apply a type to each
member, i.e.,

  private var a:Number, b:String;

I don't have the necessary tools in front of me to check this though.
Can anyone confirm the exact syntax?


thanks,
dave

-- 
http://david.holroyd.me.uk/

From kremens at gmail.com  Sun Sep  4 00:43:26 2005
From: kremens at gmail.com (Jim Kremens)
Date: Sun Sep  4 00:43:44 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <20050903221223.GB32049@badgers-in-foil.co.uk>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
	<ccedf66c05090108316a711ed1@mail.gmail.com>
	<20050901155353.GC27516@badgers-in-foil.co.uk>
	<ccedf66c0509011538591ca692@mail.gmail.com>
	<ccedf66c050901212069b8cbfe@mail.gmail.com>
	<20050903221223.GB32049@badgers-in-foil.co.uk>
Message-ID: <ccedf66c0509031743d196c6b@mail.gmail.com>

I'm sure you're right.  As I recall, MMC allows you to do this and
preserves the type of each element.  mtasc allows you to do it, but
doesn't preserve the type of each element.    The first elements go
untyped and the last element in the list gets typed.

I think the soluton is to not allow this kind of syntax, as mtasc
doesn't really allow it either.  I'll get rid of it and see if it
fixes the problem.

Thanks for the followup,

Jim Kremens

On 9/3/05, David Holroyd <dave@badgers-in-foil.co.uk> wrote:
> On Fri, Sep 02, 2005 at 12:20:46AM -0400, Jim Kremens wrote:
> > Sorry to bug you.  I think I'm doing everything right at this point,
> > but I'm still finding some issues.  as2api seems to overlook some of
> > the files in a given package.
> >
> > For example, a package might have 7 classes in it, all inheriting from
> > the same parent, and the documentation will only show 4.  Can you
> > think of any reasons for this?
> 
> Looking at the error messages produced for the problem files, I see that
> this sort of syntax is causing the problem,
> 
>   private var a, b:String;
> 
> The parser as2api uses only expects a single variable to be declared in
> such a statement.  I didn't realise that a list of variables was
> possible.
> 
> 
> Given the usage I can see in your example code, it appears that the
> type (String, in the above example) applies to all elements in the list.
> I would have thought that it would be possible to apply a type to each
> member, i.e.,
> 
>   private var a:Number, b:String;
> 
> I don't have the necessary tools in front of me to check this though.
> Can anyone confirm the exact syntax?
> 
> 
> thanks,
> dave
> 
> --
> http://david.holroyd.me.uk/
> 
> _______________________________________________
> as2api-dev mailing list
> as2api-dev@lists.badgers-in-foil.co.uk
> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
>

From dave at badgers-in-foil.co.uk  Sun Sep  4 14:17:21 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Sun Sep  4 14:17:25 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <ccedf66c0509031743d196c6b@mail.gmail.com>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
	<ccedf66c05090108316a711ed1@mail.gmail.com>
	<20050901155353.GC27516@badgers-in-foil.co.uk>
	<ccedf66c0509011538591ca692@mail.gmail.com>
	<ccedf66c050901212069b8cbfe@mail.gmail.com>
	<20050903221223.GB32049@badgers-in-foil.co.uk>
	<ccedf66c0509031743d196c6b@mail.gmail.com>
Message-ID: <20050904141721.GA9687@badgers-in-foil.co.uk>

On Sat, Sep 03, 2005 at 08:43:26PM -0400, Jim Kremens wrote:
> I'm sure you're right.  As I recall, MMC allows you to do this and
> preserves the type of each element.  mtasc allows you to do it, but
> doesn't preserve the type of each element.    The first elements go
> untyped and the last element in the list gets typed.

I've updated the parser to (hopefully) handle syntax like,

  var a, b;
  var c:String, d:Number;
  var e:String = "red", f=1;

for defining fields.  If you're using the Ruby source, you can download
an updated parse/parser.rb from,

  http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api/parse/parser.rb


> I think the soluton is to not allow this kind of syntax, as mtasc
> doesn't really allow it either.  I'll get rid of it and see if it
> fixes the problem.

If programs vaild in both MMC and MTASC (strict?) allow the syntax, I
think as2api should do a better job with it.  This syntax doesn't seem
too bogus; I just didn't spot it until now.


dave

-- 
http://david.holroyd.me.uk/

From kremens at gmail.com  Sun Sep  4 15:39:16 2005
From: kremens at gmail.com (Jim Kremens)
Date: Sun Sep  4 15:39:28 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <20050904141721.GA9687@badgers-in-foil.co.uk>
References: <ccedf66c050901065142750066@mail.gmail.com>
	<20050901142421.GB27516@badgers-in-foil.co.uk>
	<ccedf66c05090108316a711ed1@mail.gmail.com>
	<20050901155353.GC27516@badgers-in-foil.co.uk>
	<ccedf66c0509011538591ca692@mail.gmail.com>
	<ccedf66c050901212069b8cbfe@mail.gmail.com>
	<20050903221223.GB32049@badgers-in-foil.co.uk>
	<ccedf66c0509031743d196c6b@mail.gmail.com>
	<20050904141721.GA9687@badgers-in-foil.co.uk>
Message-ID: <ccedf66c050904083935eb9a4@mail.gmail.com>

Do you have an exe for Windows?

Jim

On 9/4/05, David Holroyd <dave@badgers-in-foil.co.uk> wrote:
> On Sat, Sep 03, 2005 at 08:43:26PM -0400, Jim Kremens wrote:
> > I'm sure you're right.  As I recall, MMC allows you to do this and
> > preserves the type of each element.  mtasc allows you to do it, but
> > doesn't preserve the type of each element.    The first elements go
> > untyped and the last element in the list gets typed.
> 
> I've updated the parser to (hopefully) handle syntax like,
> 
>   var a, b;
>   var c:String, d:Number;
>   var e:String = "red", f=1;
> 
> for defining fields.  If you're using the Ruby source, you can download
> an updated parse/parser.rb from,
> 
>   http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api/parse/parser.rb
> 
> 
> > I think the soluton is to not allow this kind of syntax, as mtasc
> > doesn't really allow it either.  I'll get rid of it and see if it
> > fixes the problem.
> 
> If programs vaild in both MMC and MTASC (strict?) allow the syntax, I
> think as2api should do a better job with it.  This syntax doesn't seem
> too bogus; I just didn't spot it until now.
> 
> 
> dave
> 
> --
> http://david.holroyd.me.uk/
> 
> _______________________________________________
> as2api-dev mailing list
> as2api-dev@lists.badgers-in-foil.co.uk
> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
>

From xavi at code4net.com  Mon Sep  5 08:17:11 2005
From: xavi at code4net.com (Xavi Beumala)
Date: Mon Sep  5 08:17:21 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
In-Reply-To: <431BE63E.90909@code4net.com>
References: <431BE63E.90909@code4net.com>
Message-ID: <431BFF07.6010104@code4net.com>

Great!
I've tested it and now it seems to be working :-)

Thx a lot!
X.

>
>
> -------- Original Message --------
> Subject: Re: [as2api-dev] Problem documenting getter/setter with 
> Inspectable    meta tag
> Date: Sat, 3 Sep 2005 21:43:44 +0000
> From: David Holroyd <dave@badgers-in-foil.co.uk>
> To: as2api-dev@lists.badgers-in-foil.co.uk
> References: <431711AC.3050602@code4net.com> 
> <20050902085203.GA8939@badgers-in-foil.co.uk>
>
> On Thu, Sep 01, 2005 at 04:35:24PM +0200, Xavi Beumala wrote:
>
>> I'm having problems when documenting a getter/setter property wich 
>> has  a [Inspectable] meta tag associated:
>>
>> <code>
>> /**
>> * Getter/Setter
>> */
>> public function get myVar():String {
>>  return _myVar;
>> }
>>
>> public function set myVar(mr:String) {
>> _myVar = m;
>> }
>> </code>
>>
>> The code above generates correctly the documentation for the class, 
>> but if the code changes to:
>>
>> <code>
>> [Inspectable]
>> /**
>> * Getter/Setter
>> */
>> public function get myVar():String {
>>  return _myVar;
>> }
>>
>> public function set myVar(mr:String) {
>> _myVar = m;
>> }
>> </code>
>>
>> Then as2api doesn't add the comments to the documentation.
>
>
> I think I've fixed this.  If you're using the Ruby sources, you can
> download a modified version of parse/parser.rb from here:
>
>   http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api/parse/parser.rb
>
> Otherwise, let me know what platform you're using, and I'll try to get
> an updated executable built for you some time soon.
>
>
> Thanks for reporting this bug!
> dave
>


From dave at badgers-in-foil.co.uk  Tue Sep  6 20:50:13 2005
From: dave at badgers-in-foil.co.uk (dave@badgers-in-foil.co.uk)
Date: Tue Sep  6 20:50:21 2005
Subject: [as2api-dev] [CVS trunk] Commit mail test 2
Message-ID: <E1ECkOT-0003Q8-QC@vhost.badgers-in-foil.co.uk>

An HTML attachment was scrubbed...
URL: http://lists.badgers-in-foil.co.uk/pipermail/as2api-dev/attachments/20050906/d9129f99/attachment.html
From dave at badgers-in-foil.co.uk  Tue Sep  6 21:07:09 2005
From: dave at badgers-in-foil.co.uk (dave@badgers-in-foil.co.uk)
Date: Tue Sep  6 21:41:44 2005
Subject: [as2api-dev] [CVS trunk] html_output.rb got tall enough to require
 refactoring into smaller pieces.
Message-ID: <E1ECker-0003T5-4Z@vhost.badgers-in-foil.co.uk>

An HTML attachment was scrubbed...
URL: http://lists.badgers-in-foil.co.uk/pipermail/as2api-dev/attachments/20050906/53b675f8/attachment-0001.htm
From michael.nisi at gmail.com  Fri Sep  9 09:28:36 2005
From: michael.nisi at gmail.com (Michael Nisi)
Date: Fri Sep  9 09:28:43 2005
Subject: [as2api-dev] private
Message-ID: <509850a905090902284e766b63@mail.gmail.com>

Hi,

I've just started to use as2api and really appreciate it. Thank you.

Just one thing. I need to document private methods too. Isn't that a common 
issue? There should be a command line property for this. Is it there 
already? I think most of us write applications, not libraries.

Thanks,
Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.badgers-in-foil.co.uk/pipermail/as2api-dev/attachments/20050909/26fdd0f9/attachment.html
From dave at badgers-in-foil.co.uk  Fri Sep  9 12:17:58 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Fri Sep  9 12:18:02 2005
Subject: [as2api-dev] private
In-Reply-To: <509850a905090902284e766b63@mail.gmail.com>
References: <509850a905090902284e766b63@mail.gmail.com>
Message-ID: <20050909121758.GC22895@badgers-in-foil.co.uk>

Hi there,

On Fri, Sep 09, 2005 at 11:28:36AM +0200, Michael Nisi wrote:
> Just one thing. I need to document private methods too. Isn't that a common 
> issue? There should be a command line property for this. Is it there 
> already? I think most of us write applications, not libraries.

There are lots of excellent reasons not to include private type members
in the API documentation.

Since I want to promote OO best practice, it's fairly unlikely that an
option to include all private members will be added in as2api.

Do you have a specific use-case in mind that should override normal best
practice considerations?  (e.g. I believe that it's possible to make
public in a subclass a method originally defined as private in a
superclass; if true, that's probably a bug in the MM compiler, but maybe
a case that as2api needs to handle better somehow?)


dave

-- 
http://david.holroyd.me.uk/

From michael.nisi at gmail.com  Fri Sep  9 12:34:30 2005
From: michael.nisi at gmail.com (Michael Nisi)
Date: Fri Sep  9 12:34:40 2005
Subject: [as2api-dev] private
In-Reply-To: <20050909121758.GC22895@badgers-in-foil.co.uk>
References: <509850a905090902284e766b63@mail.gmail.com>
	<20050909121758.GC22895@badgers-in-foil.co.uk>
Message-ID: <509850a9050909053457147387@mail.gmail.com>

Hi David,

I agree 100%. Documentation for an API should never include private members.

The reason for my request is quite more practible. If you work in a team, 
it's nice to use documentation as development tool. New team members can 
browse the docs, discuss code, etc. Without a feature like that we have to 
browse source and read comments there. 

The point is, I sometimes need to be able to document for the person who 
writes the API, not the one who uses it. 

Regards,
Michael

ps. give me a hint and I'll edit my version -- I'll find it anyways ;)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.badgers-in-foil.co.uk/pipermail/as2api-dev/attachments/20050909/8df48464/attachment.htm
From dave at badgers-in-foil.co.uk  Fri Sep  9 12:54:16 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Fri Sep  9 12:54:21 2005
Subject: [as2api-dev] private
In-Reply-To: <509850a9050909053457147387@mail.gmail.com>
References: <509850a905090902284e766b63@mail.gmail.com>
	<20050909121758.GC22895@badgers-in-foil.co.uk>
	<509850a9050909053457147387@mail.gmail.com>
Message-ID: <20050909125415.GD22895@badgers-in-foil.co.uk>

On Fri, Sep 09, 2005 at 02:34:30PM +0200, Michael Nisi wrote:
> Hi David,
> 
> I agree 100%. Documentation for an API should never include private members.
> 
> The reason for my request is quite more practible. If you work in a team, 
> it's nice to use documentation as development tool. New team members can 
> browse the docs, discuss code, etc. Without a feature like that we have to 
> browse source and read comments there. 
> 
> The point is, I sometimes need to be able to document for the person who 
> writes the API, not the one who uses it. 

To which the counterpoint (from the devil's advocate point of view) is
that the person trying to understand the API's implementation (of which
private methods are a part) needs to read the source anyway.


> ps. give me a hint and I'll edit my version -- I'll find it anyways ;)

Sure.  If you check out the latest code from Subversion, e.g.,

  svn checkout http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api

and look in the file 'output/html/html_framework.rb',

  http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api/output/html/html_framework.rb

you'll find a utility method in the class 'Page' called
document_member?(),

  def document_member?(member)
    !member.access.private?
  end

I think you'll get the effect you're after if you change that to,

  def document_member?(member)
    true
  end


hope that helps,
dave

-- 
http://david.holroyd.me.uk/

From rostislav.hristov at gmail.com  Fri Sep  9 12:56:08 2005
From: rostislav.hristov at gmail.com (Rostislav Hristov)
Date: Fri Sep  9 12:56:18 2005
Subject: [as2api-dev] private
In-Reply-To: <509850a9050909053457147387@mail.gmail.com>
References: <509850a905090902284e766b63@mail.gmail.com>
	<20050909121758.GC22895@badgers-in-foil.co.uk>
	<509850a9050909053457147387@mail.gmail.com>
Message-ID: <435de143050909055665177de7@mail.gmail.com>

In ActionScript2 there are no protected members. This leads to an
increased usage of private members as a replacement. Sometimes it's
useful to document these exceptions.

-Rostislav


-- 
EnFlash - It's all about features...
http://www.asual.com/enflash/

From michael.nisi at gmail.com  Fri Sep  9 13:04:10 2005
From: michael.nisi at gmail.com (Michael Nisi)
Date: Fri Sep  9 13:04:17 2005
Subject: [as2api-dev] private
In-Reply-To: <20050909125415.GD22895@badgers-in-foil.co.uk>
References: <509850a905090902284e766b63@mail.gmail.com>
	<20050909121758.GC22895@badgers-in-foil.co.uk>
	<509850a9050909053457147387@mail.gmail.com>
	<20050909125415.GD22895@badgers-in-foil.co.uk>
Message-ID: <509850a9050909060463863865@mail.gmail.com>

Thank you.

Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.badgers-in-foil.co.uk/pipermail/as2api-dev/attachments/20050909/e7ea1644/attachment.html
From rostislav.hristov at gmail.com  Fri Sep  9 15:50:26 2005
From: rostislav.hristov at gmail.com (Rostislav Hristov)
Date: Fri Sep  9 15:50:40 2005
Subject: [as2api-dev] private
In-Reply-To: <20050909154126.GE22895@badgers-in-foil.co.uk>
References: <509850a905090902284e766b63@mail.gmail.com>
	<20050909121758.GC22895@badgers-in-foil.co.uk>
	<509850a9050909053457147387@mail.gmail.com>
	<435de143050909055665177de7@mail.gmail.com>
	<20050909154126.GE22895@badgers-in-foil.co.uk>
Message-ID: <435de143050909085030b391ed@mail.gmail.com>

> I don't see how as2api could identify cases of private-but-protected-
> really methods, and differentiate them from private-and-really-private
> methods.

I don't think that there is a way to identify these. Even the compilers can't.

The only good option is to document private methods that have the
proper comments only. You cannot force the best practices this way,
it's all up to the user.


Cheers,
Rostislav


-- 
EnFlash - It's all about features...
http://www.asual.com/enflash/

From rostislav.hristov at gmail.com  Fri Sep  9 18:47:57 2005
From: rostislav.hristov at gmail.com (Rostislav Hristov)
Date: Fri Sep  9 18:48:09 2005
Subject: [as2api-dev] private
In-Reply-To: <509850a90509091045178d03c8@mail.gmail.com>
References: <509850a905090902284e766b63@mail.gmail.com>
	<20050909121758.GC22895@badgers-in-foil.co.uk>
	<509850a9050909053457147387@mail.gmail.com>
	<435de143050909055665177de7@mail.gmail.com>
	<20050909154126.GE22895@badgers-in-foil.co.uk>
	<435de143050909085030b391ed@mail.gmail.com>
	<509850a90509091045178d03c8@mail.gmail.com>
Message-ID: <435de14305090911475997cebf@mail.gmail.com>

Dave,

I don't remember how this list was configured before, but it looks
like you have to enable the reply-to overriding. The so called
"munging" is not so good, but at least it helps for keeping the whole
conversation viewable by everybody. Most of the people don't manually
specify the address of the list.


Rostislav



On 9/9/05, Michael Nisi <michael.nisi@gmail.com> wrote:
> Best practices should never be forced, always optional -- all is relative.
> ;)
>  
>  Cheers,
>  Michael
>  


-- 
EnFlash - It's all about features...
http://www.asual.com/enflash/

From dave at badgers-in-foil.co.uk  Sun Sep 11 15:58:28 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Sun Sep 11 15:58:32 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <ccedf66c05091020065a8aa8d0@mail.gmail.com>
References: <20050901155353.GC27516@badgers-in-foil.co.uk>
	<ccedf66c0509011538591ca692@mail.gmail.com>
	<ccedf66c050901212069b8cbfe@mail.gmail.com>
	<20050903221223.GB32049@badgers-in-foil.co.uk>
	<ccedf66c0509031743d196c6b@mail.gmail.com>
	<20050904141721.GA9687@badgers-in-foil.co.uk>
	<ccedf66c050904083935eb9a4@mail.gmail.com>
	<ccedf66c05090611171df0ce48@mail.gmail.com>
	<20050907152503.GB20458@badgers-in-foil.co.uk>
	<ccedf66c05091020065a8aa8d0@mail.gmail.com>
Message-ID: <20050911155828.GA28036@badgers-in-foil.co.uk>

On Sat, Sep 10, 2005 at 11:06:55PM -0400, Jim Kremens wrote:
> Hi David,
> 
> It works!  Parsed the whole library with no problems.  I'm eager to
> start using it, but I have a few questions.

Great!


> Can it handle intrinsic getter/setters?  The following doesn't produce
> any text in the docs:
> 
> 	/**
> 	 * Set and get style preset for instance.  
> 	 * @param styleName:String. 
> 	 */
> 	public function set style(val:Object) {
> 	}
> 	public function get style():Object {
> 		return __style;
> 	}	

Yes, they should be handled.  Note that properties defined implicitly
with get/set methods are listed in the 'Fields' section of the class
API, not in the 'Methods' section.


> Also, regarding styling, it would be great to be able to specify an
> external stylesheet.

Yep, I need to add that in.  Your ant task could copy a replacement file
over the existing one until then though.


Thanks for letting us know the fix works!
dave

From kremens at gmail.com  Sun Sep 11 19:50:02 2005
From: kremens at gmail.com (Jim Kremens)
Date: Sun Sep 11 19:50:20 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <20050911155828.GA28036@badgers-in-foil.co.uk>
References: <20050901155353.GC27516@badgers-in-foil.co.uk>
	<ccedf66c050901212069b8cbfe@mail.gmail.com>
	<20050903221223.GB32049@badgers-in-foil.co.uk>
	<ccedf66c0509031743d196c6b@mail.gmail.com>
	<20050904141721.GA9687@badgers-in-foil.co.uk>
	<ccedf66c050904083935eb9a4@mail.gmail.com>
	<ccedf66c05090611171df0ce48@mail.gmail.com>
	<20050907152503.GB20458@badgers-in-foil.co.uk>
	<ccedf66c05091020065a8aa8d0@mail.gmail.com>
	<20050911155828.GA28036@badgers-in-foil.co.uk>
Message-ID: <ccedf66c050911125036f5ab7@mail.gmail.com>

The fix does work, but there are still some other problems... spoke too soon!

I'll send you a zip of the problem files in a bit to see if you can
figure out why parsing stops short...

Jim

On 9/11/05, David Holroyd <dave@badgers-in-foil.co.uk> wrote:
> On Sat, Sep 10, 2005 at 11:06:55PM -0400, Jim Kremens wrote:
> > Hi David,
> >
> > It works!  Parsed the whole library with no problems.  I'm eager to
> > start using it, but I have a few questions.
> 
> Great!
> 
> 
> > Can it handle intrinsic getter/setters?  The following doesn't produce
> > any text in the docs:
> >
> >       /**
> >        * Set and get style preset for instance.
> >        * @param styleName:String.
> >        */
> >       public function set style(val:Object) {
> >       }
> >       public function get style():Object {
> >               return __style;
> >       }
> 
> Yes, they should be handled.  Note that properties defined implicitly
> with get/set methods are listed in the 'Fields' section of the class
> API, not in the 'Methods' section.
> 
> 
> > Also, regarding styling, it would be great to be able to specify an
> > external stylesheet.
> 
> Yep, I need to add that in.  Your ant task could copy a replacement file
> over the existing one until then though.
> 
> 
> Thanks for letting us know the fix works!
> dave
> 
> _______________________________________________
> as2api-dev mailing list
> as2api-dev@lists.badgers-in-foil.co.uk
> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
>

From kremens at gmail.com  Sun Sep 11 21:56:32 2005
From: kremens at gmail.com (Jim Kremens)
Date: Sun Sep 11 21:58:05 2005
Subject: [as2api-dev] error: No packages specified
In-Reply-To: <ccedf66c050911125036f5ab7@mail.gmail.com>
References: <20050901155353.GC27516@badgers-in-foil.co.uk>
	<20050903221223.GB32049@badgers-in-foil.co.uk>
	<ccedf66c0509031743d196c6b@mail.gmail.com>
	<20050904141721.GA9687@badgers-in-foil.co.uk>
	<ccedf66c050904083935eb9a4@mail.gmail.com>
	<ccedf66c05090611171df0ce48@mail.gmail.com>
	<20050907152503.GB20458@badgers-in-foil.co.uk>
	<ccedf66c05091020065a8aa8d0@mail.gmail.com>
	<20050911155828.GA28036@badgers-in-foil.co.uk>
	<ccedf66c050911125036f5ab7@mail.gmail.com>
Message-ID: <ccedf66c0509111456cbfa612@mail.gmail.com>

Actually, let me take that back.  It looks like it parsed everything
fine.  I'll use it for a while before making any more comments...

It's interesting how seeing your code documented makes you catch
things you otherwise would have missed.  Public members that should be
private, etc...

Good idea re: the Ant task to swap CSS stylesheets.  I'll give that a try.

Thanks,

Jim

On 9/11/05, Jim Kremens <kremens@gmail.com> wrote:
> The fix does work, but there are still some other problems... spoke too soon!
> 
> I'll send you a zip of the problem files in a bit to see if you can
> figure out why parsing stops short...
> 
> Jim
> 
> On 9/11/05, David Holroyd <dave@badgers-in-foil.co.uk> wrote:
> > On Sat, Sep 10, 2005 at 11:06:55PM -0400, Jim Kremens wrote:
> > > Hi David,
> > >
> > > It works!  Parsed the whole library with no problems.  I'm eager to
> > > start using it, but I have a few questions.
> >
> > Great!
> >
> >
> > > Can it handle intrinsic getter/setters?  The following doesn't produce
> > > any text in the docs:
> > >
> > >       /**
> > >        * Set and get style preset for instance.
> > >        * @param styleName:String.
> > >        */
> > >       public function set style(val:Object) {
> > >       }
> > >       public function get style():Object {
> > >               return __style;
> > >       }
> >
> > Yes, they should be handled.  Note that properties defined implicitly
> > with get/set methods are listed in the 'Fields' section of the class
> > API, not in the 'Methods' section.
> >
> >
> > > Also, regarding styling, it would be great to be able to specify an
> > > external stylesheet.
> >
> > Yep, I need to add that in.  Your ant task could copy a replacement file
> > over the existing one until then though.
> >
> >
> > Thanks for letting us know the fix works!
> > dave
> >
> > _______________________________________________
> > as2api-dev mailing list
> > as2api-dev@lists.badgers-in-foil.co.uk
> > http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
> >
>

From dave at badgers-in-foil.co.uk  Sun Sep 11 21:58:36 2005
From: dave at badgers-in-foil.co.uk (dave@badgers-in-foil.co.uk)
Date: Sun Sep 11 21:58:39 2005
Subject: [as2api-dev] [CVS trunk] Delete old (now broken) require line
Message-ID: <E1EEZqO-0000Aj-AO@vhost.badgers-in-foil.co.uk>

An HTML attachment was scrubbed...
URL: http://lists.badgers-in-foil.co.uk/pipermail/as2api-dev/attachments/20050911/cdfb47fa/attachment.htm
From dave at badgers-in-foil.co.uk  Sun Sep 11 21:59:59 2005
From: dave at badgers-in-foil.co.uk (dave@badgers-in-foil.co.uk)
Date: Sun Sep 11 22:00:19 2005
Subject: [as2api-dev] [CVS trunk] Ensure prerequisite module is available
Message-ID: <E1EEZrj-0000FM-Gd@vhost.badgers-in-foil.co.uk>

An HTML attachment was scrubbed...
URL: http://lists.badgers-in-foil.co.uk/pipermail/as2api-dev/attachments/20050911/e95170ff/attachment.html
From dave at badgers-in-foil.co.uk  Sun Sep 11 23:25:15 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Sun Sep 11 23:25:21 2005
Subject: [as2api-dev] as2lib to as2api
In-Reply-To: <c7d0744705082705585df2a47e@mail.gmail.com>
References: <c7d074470508251315214f7893@mail.gmail.com>
	<20050827112256.GA14072@badgers-in-foil.co.uk>
	<c7d0744705082705585df2a47e@mail.gmail.com>
Message-ID: <20050911232515.GA31951@badgers-in-foil.co.uk>

On Sat, Aug 27, 2005 at 02:58:27PM +0200, martin heidegger wrote:
> > On Thu, Aug 25, 2005 at 10:15:06PM +0200, martin heidegger wrote:
> > > we from the as2lib are just discussing about changing from visdoc to
> > > as2api because its rather problematic to argue with some developers:
> > > go get a mac to work with us, and there are some questions open:

> > > * How is the current state for a different output template. How
> > > complex is it to write such or template or are you planning to update
> > > your template. We would invest some time for this...

> > Roughly, what changes are you considering?
> 
> Two frame - frameset and a dhtml tree, that is based on xhtml ... 

So, I've been doing some reorganisation of the output-generating code
to make this task a little easier.  I've got things to the point where
it's possible to hack-in some code to replace the existing frameset
stuff *assuming that you are invoking the ruby scripts* rather than
using the stand-alone (exe) versions.

This is far from being a final / stable / proper way of changing the
templates, but should give you an idea of what custom templates would
look like.

Attached is an example customisation which replaces the standard
three-frame layout with a two-frame version; the left hand frame
containing a (non-DHTML) tree of packages and types.  This is simply to
serve as an example, so it's fairly rough.

To make use of this hack (and assuming that you've got the attached file
in the current directory, together with the rest of the as2api files),
the option

  -r frameset_override

must be added to your ruby invocation before the as2api.rb script is
named.  For example:

  ruby -r frameset_override as2api.rb \
       --classpath eg/as2lib_0.9.2/src \
       org.as2lib.*

For a while, you'll be able to see an example of the resulting output
here:

 http://www.badgers-in-foil.co.uk/projects/as2api/tmp/tree-example/frameset.html


hope that helps,
dave

-- 
http://david.holroyd.me.uk/
-------------- next part --------------

require 'output/html/driver'

# reopen the class originally defined in output/html/driver
class PageListBuilder
  # redefine the instance methods of PageListBuilder which control frameset
  # production (will produce warnings -- there's a way to avoid this by
  # deleting the old method definitions first, but I forget the required magic)
  
  def build_toplevel_frameset_pages(list)
    list << TwoFrameFramesetPage.new()
    list << TreeNavFramePage.new(@type_agregator)
  end

  # just replace original definition with no-op method
  def build_package_frameset_pages(list, package); end
end

# simple frameset
class TwoFrameFramesetPage < Page
  def initialize
    super("frameset")
    @doctype_id = :frameset
  end

  def generate_content
    html_frameset("cols"=>"20%,80%") do
      html_frame("src"=>"treenav-frame.html",
			"name"=>"all_packages_frame",
			"title"=>"Navigation")
      html_frame("src"=>"overview-summary.html",
                        "name"=>"type_frame",
                        "title"=>"Package and type descriptions")
      html_noframes do
	html_body do
	  html_a("Non-frameset overview page", {"href"=>"overview-summary.html"})
	end
      end
    end
  end

  def extra_metadata
    # this page isn't interesting
    {
      "robots" => "noindex"
    }
  end
end


# tree navigation for left-hand frame
class TreeNavFramePage < Page

  def initialize(type_agregator)
    super("treenav-frame")
    @type_agregator = type_agregator
    @doctype_id = :transitional
  end

  def generate_content
    hash_tree = build_tree(@type_agregator.types)
    html_body do
      html_h3("All Types")
      gen_tree(hash_tree)
    end
  end

  def extra_metadata
    # this page isn't interesting
    {
      "robots" => "noindex"
    }
  end

  private

  # un-flatten package names into a tree of Hash objects, with types at leaves
  def build_tree(types)
    tree = {}
    types.each do |type|
      # TODO: cope with default package,
      namespace = tree
      type.package_name.split(/\./).each do |bit|
	ns = namespace[bit]
	if ns.nil?
	  ns = {}
	  namespace[bit] = ns
	end
	namespace = ns
      end
      namespace[type.unqualified_name] = type
    end
    tree
  end

  # recursively generate HTML for the nav tree
  def gen_tree(node)
    html_ul do
      node.keys.sort_by{|k| k.downcase}.each do |key|
	html_li do
	  val = node[key]
	  if val.is_a?(Hash)
	    pcdata(key)
	    gen_tree(val)
	  else
	    link_type(val, false, {"target"=>"type_frame"})
	  end
	end
      end
    end
  end
end



# vim:softtabstop=2:shiftwidth=2
From dave at badgers-in-foil.co.uk  Wed Sep 14 10:44:45 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Wed Sep 14 10:44:50 2005
Subject: [as2api-dev] Re: multiple classpaths using Ant
In-Reply-To: <ccedf66c05091312207317034c@mail.gmail.com>
References: <ccedf66c05091312207317034c@mail.gmail.com>
Message-ID: <20050914104445.GA14483@badgers-in-foil.co.uk>

On Tue, Sep 13, 2005 at 03:20:21PM -0400, Jim Kremens wrote:
> Hi David,
> 
> I'm really enjoying using as2api.  I hope my comments about the
> stylesheet did not offend!

Not at all!  Just been too busy to write a proper reply.


> Anyway, I'm trying to send multiple packages to as2api, but can't seem
> to get it working.  Here's my Ant task:
> 
> 	<target name="document">
> 		<exec executable="${as2api}" failonerror="false">
> 			<arg value='org.flashcodersny.*'/>
> 			<arg line='--classpath "${dist}" --classpath "${macromedia_classes}"'/>
> 			<arg line='--output-dir "${docs}"'/>
> 			<arg line='--sources'/>
> 			<arg line='--draw-diagrams --dot-exe "${graphviz}"'/>	
> 		</exec>
> 		<delete file="${docs}/style.css" />
> 		<copy file="../utilities/style.css" todir="${docs}"/>
> 	</target>

What is it that actually goes wrong?  Error message?  Unexpected output?

Can you get ant to show you exactly the command line it tries to execute,
and post that too?


> Note that I'm passing in ''org.flashcodersny.*'  What I'd really like
> to do is pass in org.* to get all of the packages in org.  Is that
> possible?  If not, what syntax should I use to pass in multiple
> packages?

If you always want to document all classes packaged under 'org/..', then
you should indeed be able to just use 'org.*'.  When you start making
use of other libs which are also in the org namespace, this may not be
desirable though.


thanks,
dave

From kremens at gmail.com  Wed Sep 14 18:11:18 2005
From: kremens at gmail.com (Jim Kremens)
Date: Wed Sep 14 18:11:33 2005
Subject: [as2api-dev] Re: multiple classpaths using Ant
In-Reply-To: <20050914104445.GA14483@badgers-in-foil.co.uk>
References: <ccedf66c05091312207317034c@mail.gmail.com>
	<20050914104445.GA14483@badgers-in-foil.co.uk>
Message-ID: <ccedf66c05091411117639cb9@mail.gmail.com>

Actually, everything seems to be working pretty well.  It was failing
to document my .com package, and i blamed it on as2api.  I didin't
write the classes in my .com package, and they are kind of dodgy, so
I'm guessing that as2api doesn't like something in one of the files in
there...  Would you like me to pass them along for testing?

That said, it's now doing a wonderful job of documenting my stuff. 
Here's my revised Ant task, which allows you to pass in multiple
packages using package-spec.  I hadn't read that part of the
documentation carefully enough...

	<target name="document">
		<exec executable="${as2api}" failonerror="false">
			<arg line='package-spec org.* package-spec unit.*' />
			<arg line='--classpath "${dist}" --classpath "${macromedia_classes}"' />
			<arg line='--output-dir "${docs}"' />
			<arg line='--sources' />
			<arg line='--draw-diagrams --dot-exe "${graphviz}"' />
		</exec>
		<delete file="${docs}/style.css" />
		<copy file="../utilities/style.css" todir="${docs}" />
	</target>

I think the program is getting pretty solid... Nice work.

Jim

On 9/14/05, David Holroyd <dave@badgers-in-foil.co.uk> wrote:
> On Tue, Sep 13, 2005 at 03:20:21PM -0400, Jim Kremens wrote:
> > Hi David,
> >
> > I'm really enjoying using as2api.  I hope my comments about the
> > stylesheet did not offend!
> 
> Not at all!  Just been too busy to write a proper reply.
> 
> 
> > Anyway, I'm trying to send multiple packages to as2api, but can't seem
> > to get it working.  Here's my Ant task:
> >
> >       <target name="document">
> >               <exec executable="${as2api}" failonerror="false">
> >                       <arg value='org.flashcodersny.*'/>
> >                       <arg line='--classpath "${dist}" --classpath "${macromedia_classes}"'/>
> >                       <arg line='--output-dir "${docs}"'/>
> >                       <arg line='--sources'/>
> >                       <arg line='--draw-diagrams --dot-exe "${graphviz}"'/>
> >               </exec>
> >               <delete file="${docs}/style.css" />
> >               <copy file="../utilities/style.css" todir="${docs}"/>
> >       </target>
> 
> What is it that actually goes wrong?  Error message?  Unexpected output?
> 
> Can you get ant to show you exactly the command line it tries to execute,
> and post that too?
> 
> 
> > Note that I'm passing in ''org.flashcodersny.*'  What I'd really like
> > to do is pass in org.* to get all of the packages in org.  Is that
> > possible?  If not, what syntax should I use to pass in multiple
> > packages?
> 
> If you always want to document all classes packaged under 'org/..', then
> you should indeed be able to just use 'org.*'.  When you start making
> use of other libs which are also in the org namespace, this may not be
> desirable though.
> 
> 
> thanks,
> dave
> 
> _______________________________________________
> as2api-dev mailing list
> as2api-dev@lists.badgers-in-foil.co.uk
> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
>

From xavi at code4net.com  Thu Sep 15 11:56:33 2005
From: xavi at code4net.com (Xavi Beumala)
Date: Thu Sep 15 11:57:39 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
In-Reply-To: <431BFF07.6010104@code4net.com>
References: <431BE63E.90909@code4net.com> <431BFF07.6010104@code4net.com>
Message-ID: <43296171.6050303@code4net.com>

Hi all,

I've checkout the last review of as2api from svn (I want to be able to 
document methods with [Inspectable] metadata).

But when I run my ant script (is working with windows build) I'm getting 
  the following errors:

   [exec] ./api_model.rb:185:in `each_implemented_interface': undefined 
method `each_interface' for #<ASInterface:0x2cb2248> (NoMethodError)
      [exec] from ./api_model.rb:184:in `each_ancestor'
      [exec] from ./api_model.rb:184:in `each_implemented_interface'
      [exec] from ./api_model.rb:306:in `inherited_comment'
      [exec] from ./output/html/core_pages.rb:332:in `document_method'
      [exec] from ./output/html/core_pages.rb:307:in `html_div'
      [exec] from (eval):3:in `element'
      [exec] from (eval):3:in `html_div'
      [exec] from ./output/html/core_pages.rb:307:in `document_method'
      [exec] ... 34 levels...
      [exec] from ./ui/cli.rb:285
      [exec] from 
c:/developer/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:18:in 
`require__'
      [exec] from 
c:/developer/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:18:in 
`require'
      [exec] from as2api.rb:3


I don't understand anything at all :S I'm missing something?

Many thanks,
Cheers
X.


Xavi Beumala wrote:
> Great!
> I've tested it and now it seems to be working :-)
> 
> Thx a lot!
> X.
> 
>>
>>
>> -------- Original Message --------
>> Subject: Re: [as2api-dev] Problem documenting getter/setter with 
>> Inspectable    meta tag
>> Date: Sat, 3 Sep 2005 21:43:44 +0000
>> From: David Holroyd <dave@badgers-in-foil.co.uk>
>> To: as2api-dev@lists.badgers-in-foil.co.uk
>> References: <431711AC.3050602@code4net.com> 
>> <20050902085203.GA8939@badgers-in-foil.co.uk>
>>
>> On Thu, Sep 01, 2005 at 04:35:24PM +0200, Xavi Beumala wrote:
>>
>>> I'm having problems when documenting a getter/setter property wich 
>>> has  a [Inspectable] meta tag associated:
>>>
>>> <code>
>>> /**
>>> * Getter/Setter
>>> */
>>> public function get myVar():String {
>>>  return _myVar;
>>> }
>>>
>>> public function set myVar(mr:String) {
>>> _myVar = m;
>>> }
>>> </code>
>>>
>>> The code above generates correctly the documentation for the class, 
>>> but if the code changes to:
>>>
>>> <code>
>>> [Inspectable]
>>> /**
>>> * Getter/Setter
>>> */
>>> public function get myVar():String {
>>>  return _myVar;
>>> }
>>>
>>> public function set myVar(mr:String) {
>>> _myVar = m;
>>> }
>>> </code>
>>>
>>> Then as2api doesn't add the comments to the documentation.
>>
>>
>>
>> I think I've fixed this.  If you're using the Ruby sources, you can
>> download a modified version of parse/parser.rb from here:
>>
>>   http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api/parse/parser.rb
>>
>> Otherwise, let me know what platform you're using, and I'll try to get
>> an updated executable built for you some time soon.
>>
>>
>> Thanks for reporting this bug!
>> dave
>>
> 
> 
> _______________________________________________
> as2api-dev mailing list
> as2api-dev@lists.badgers-in-foil.co.uk
> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
> 
> 


From xavi at code4net.com  Thu Sep 15 12:06:34 2005
From: xavi at code4net.com (Xavi Beumala)
Date: Thu Sep 15 12:06:49 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
In-Reply-To: <43296171.6050303@code4net.com>
References: <431BE63E.90909@code4net.com> <431BFF07.6010104@code4net.com>
	<43296171.6050303@code4net.com>
Message-ID: <432963CA.8090307@code4net.com>

After testing it again with the binary,
it also doesn't work. It seems there's some kind of problem with interfaces.

Is ther any known issue?

X.


Xavi Beumala wrote:
> Hi all,
> 
> I've checkout the last review of as2api from svn (I want to be able to 
> document methods with [Inspectable] metadata).
> 
> But when I run my ant script (is working with windows build) I'm getting 
>  the following errors:
> 
>   [exec] ./api_model.rb:185:in `each_implemented_interface': undefined 
> method `each_interface' for #<ASInterface:0x2cb2248> (NoMethodError)
>      [exec] from ./api_model.rb:184:in `each_ancestor'
>      [exec] from ./api_model.rb:184:in `each_implemented_interface'
>      [exec] from ./api_model.rb:306:in `inherited_comment'
>      [exec] from ./output/html/core_pages.rb:332:in `document_method'
>      [exec] from ./output/html/core_pages.rb:307:in `html_div'
>      [exec] from (eval):3:in `element'
>      [exec] from (eval):3:in `html_div'
>      [exec] from ./output/html/core_pages.rb:307:in `document_method'
>      [exec] ... 34 levels...
>      [exec] from ./ui/cli.rb:285
>      [exec] from 
> c:/developer/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:18:in 
> `require__'
>      [exec] from 
> c:/developer/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:18:in 
> `require'
>      [exec] from as2api.rb:3
> 
> 
> I don't understand anything at all :S I'm missing something?
> 
> Many thanks,
> Cheers
> X.
> 
> 
> Xavi Beumala wrote:
> 
>> Great!
>> I've tested it and now it seems to be working :-)
>>
>> Thx a lot!
>> X.
>>
>>>
>>>
>>> -------- Original Message --------
>>> Subject: Re: [as2api-dev] Problem documenting getter/setter with 
>>> Inspectable    meta tag
>>> Date: Sat, 3 Sep 2005 21:43:44 +0000
>>> From: David Holroyd <dave@badgers-in-foil.co.uk>
>>> To: as2api-dev@lists.badgers-in-foil.co.uk
>>> References: <431711AC.3050602@code4net.com> 
>>> <20050902085203.GA8939@badgers-in-foil.co.uk>
>>>
>>> On Thu, Sep 01, 2005 at 04:35:24PM +0200, Xavi Beumala wrote:
>>>
>>>> I'm having problems when documenting a getter/setter property wich 
>>>> has  a [Inspectable] meta tag associated:
>>>>
>>>> <code>
>>>> /**
>>>> * Getter/Setter
>>>> */
>>>> public function get myVar():String {
>>>>  return _myVar;
>>>> }
>>>>
>>>> public function set myVar(mr:String) {
>>>> _myVar = m;
>>>> }
>>>> </code>
>>>>
>>>> The code above generates correctly the documentation for the class, 
>>>> but if the code changes to:
>>>>
>>>> <code>
>>>> [Inspectable]
>>>> /**
>>>> * Getter/Setter
>>>> */
>>>> public function get myVar():String {
>>>>  return _myVar;
>>>> }
>>>>
>>>> public function set myVar(mr:String) {
>>>> _myVar = m;
>>>> }
>>>> </code>
>>>>
>>>> Then as2api doesn't add the comments to the documentation.
>>>
>>>
>>>
>>>
>>> I think I've fixed this.  If you're using the Ruby sources, you can
>>> download a modified version of parse/parser.rb from here:
>>>
>>>   http://svn.badgers-in-foil.co.uk/as2api/trunk/as2api/parse/parser.rb
>>>
>>> Otherwise, let me know what platform you're using, and I'll try to get
>>> an updated executable built for you some time soon.
>>>
>>>
>>> Thanks for reporting this bug!
>>> dave
>>>
>>
>>
>> _______________________________________________
>> as2api-dev mailing list
>> as2api-dev@lists.badgers-in-foil.co.uk
>> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
>>
>>
> 
> 
> _______________________________________________
> as2api-dev mailing list
> as2api-dev@lists.badgers-in-foil.co.uk
> http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev
> 
> 


From dave at badgers-in-foil.co.uk  Thu Sep 15 12:32:59 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Thu Sep 15 12:33:02 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
In-Reply-To: <43296171.6050303@code4net.com>
References: <431BE63E.90909@code4net.com> <431BFF07.6010104@code4net.com>
	<43296171.6050303@code4net.com>
Message-ID: <20050915123259.GB27783@badgers-in-foil.co.uk>

Hi there,

On Thu, Sep 15, 2005 at 01:56:33PM +0200, Xavi Beumala wrote:
> I've checkout the last review of as2api from svn (I want to be able to 
> document methods with [Inspectable] metadata).
> 
> But when I run my ant script (is working with windows build) I'm getting 
> the following errors:
> 
>   [exec] ./api_model.rb:185:in `each_implemented_interface': undefined method `each_interface' for #<ASInterface:0x2cb2248> (NoMethodError)
>   [exec] from ./api_model.rb:184:in `each_ancestor'
>   [exec] from ./api_model.rb:184:in `each_implemented_interface'
>   [exec] from ./api_model.rb:306:in `inherited_comment'
>   [exec] from ./output/html/core_pages.rb:332:in `document_method'
>   [exec] from ./output/html/core_pages.rb:307:in `html_div'
>   [exec] from (eval):3:in `element'
>   [exec] from (eval):3:in `html_div'
>   [exec] from ./output/html/core_pages.rb:307:in `document_method'
>   [exec] ... 34 levels...
>   [exec] from ./ui/cli.rb:285
>   [exec] from c:/developer/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:18:in `require__'
>   [exec] from c:/developer/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:18:in `require'
>   [exec] from as2api.rb:3

I don't suppose that you've got an instance somewhere of...

  class A extends B { ... }

...where 'B' is actually an interface rather than a class, do you?


If this is a bug in as2api, it would be very helpeful to see the source
you're trying to document (send it in a private email if you wish -- I
can treat it as confidential).


thanks for reporting the problem!
dave

-- 
http://david.holroyd.me.uk/

From dave at badgers-in-foil.co.uk  Thu Sep 15 12:57:24 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Thu Sep 15 12:57:30 2005
Subject: [as2api-dev] Re: multiple classpaths using Ant
In-Reply-To: <ccedf66c05091411117639cb9@mail.gmail.com>
References: <ccedf66c05091312207317034c@mail.gmail.com>
	<20050914104445.GA14483@badgers-in-foil.co.uk>
	<ccedf66c05091411117639cb9@mail.gmail.com>
Message-ID: <20050915125723.GC27783@badgers-in-foil.co.uk>

On Wed, Sep 14, 2005 at 02:11:18PM -0400, Jim Kremens wrote:
> Actually, everything seems to be working pretty well.  It was failing
> to document my .com package, and i blamed it on as2api.  I didin't
> write the classes in my .com package, and they are kind of dodgy, so
> I'm guessing that as2api doesn't like something in one of the files in
> there...  Would you like me to pass them along for testing?

Yep, it would be good to be able to check that.


> That said, it's now doing a wonderful job of documenting my stuff. 
> Here's my revised Ant task, which allows you to pass in multiple
> packages using package-spec.  I hadn't read that part of the
> documentation carefully enough...

I obviously need to do a much better job on that patch of the docs...

> 	<target name="document">
> 		<exec executable="${as2api}" failonerror="false">
> 			<arg line='package-spec org.* package-spec unit.*' />

...the text 'package-spec' was just meant to be a placeholder meaning
'stick your package specifications at this point', so the above should
actually just be:

     <arg line='org.* unit.*' />

I'll try to rework it at some point so that it states that in a less
convoluted way.


good to hear that things are working well otherwise,
dave

-- 
http://david.holroyd.me.uk/

From xavi at code4net.com  Thu Sep 15 14:11:10 2005
From: xavi at code4net.com (Xavi Beumala)
Date: Thu Sep 15 14:11:29 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
In-Reply-To: <20050915123259.GB27783@badgers-in-foil.co.uk>
References: <431BE63E.90909@code4net.com>
	<431BFF07.6010104@code4net.com>	<43296171.6050303@code4net.com>
	<20050915123259.GB27783@badgers-in-foil.co.uk>
Message-ID: <432980FE.2070909@code4net.com>

> I don't suppose that you've got an instance somewhere of...
> 
>   class A extends B { ... }
> 
> ...where 'B' is actually an interface rather than a class, do you?

That was it :(

Sorry for my slip-up :S I did a refactor of my code and forgot to change 
a class... :P

thanks a lot

X.

From dave at badgers-in-foil.co.uk  Thu Sep 15 14:24:18 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Thu Sep 15 14:24:55 2005
Subject: [as2api-dev] Problem documenting getter/setter with Inspectable
	meta tag
In-Reply-To: <432980FE.2070909@code4net.com>
References: <431BE63E.90909@code4net.com> <431BFF07.6010104@code4net.com>
	<43296171.6050303@code4net.com>
	<20050915123259.GB27783@badgers-in-foil.co.uk>
	<432980FE.2070909@code4net.com>
Message-ID: <20050915142418.GE27783@badgers-in-foil.co.uk>

On Thu, Sep 15, 2005 at 04:11:10PM +0200, Xavi Beumala wrote:
> >I don't suppose that you've got an instance somewhere of...
> >
> >  class A extends B { ... }
> >
> >...where 'B' is actually an interface rather than a class, do you?
> 
> That was it :(
> 
> Sorry for my slip-up :S I did a refactor of my code and forgot to change 
> a class... :P

No problem -- this reveals some missing error checking in as2api.  It
should spot this coding error earlier.


thanks for getting back to us!
dave

-- 
http://david.holroyd.me.uk/

From dave at badgers-in-foil.co.uk  Thu Sep 22 13:10:45 2005
From: dave at badgers-in-foil.co.uk (David Holroyd)
Date: Thu Sep 22 13:10:49 2005
Subject: [as2api-dev] Re: strange error
In-Reply-To: <ccedf66c05091910046c8ba969@mail.gmail.com>
References: <ccedf66c05091910046c8ba969@mail.gmail.com>
Message-ID: <20050922131044.GD11162@badgers-in-foil.co.uk>

Hi, sorry about the late reply, I got back from holiday yesterday,

On Mon, Sep 19, 2005 at 01:04:29PM -0400, Jim Kremens wrote:
> Hi David,
> 
> I'm getting this error:
> 
> Couldn't resolve import of "mx.utils.Delegate"
> 
> I've defined an Ant property like so:
> 
> <property name="macromedia_classes" location="C:\Documents and
> Settings\kremensj\Local Settings\Application Data\Macromedia\Flash MX
> 2004\en\Configuration\Classes"/>
> 
> 
> And passed it to as2api like so:
> 
> <arg line='--classpath "${macromedia_classes}"' />
> 
> the mx package resides insied this classpath, so it should be able to
> find it, right?

Yeah, that all looks fine.  Are any parse errors for that file reported
earlier on in the as2api output?  I'll try to give it a go with the
version of Delegate.as which I've got some time in the next few days.


dave

--
http://david.holroyd.me.uk/