[as2api-dev] Metatags and a couple of suggestions

[David Holroyd]

On Fri, Jul 15, 2005 at 05:25:59PM +0300, Gaspy wrote:
> > Ah, I see. The current parser only allows these attributes to appear
> > immediately preceeding the type definition.
> > 
> > I guess they need to be allowed before the import statements too, but do
> > you know if they should be allowed to appear interspersed within the
> > import list? I suspect that they should be allowed there.
> > 
> Dave, yes, I moved the import list above the metatags and it works now.
> 
> I think the parser shoud work regardless of the position of the metatags...

I've commited a change which should fix this (I hope).


> I also noted a few things I want to comment on:
> 
> 1. If a class declares a method to be public and then a descendant class 
> overrides that method and makes it private, as2doc will still create the 
> documentation for the private method, copying it from the super class. Now, 
> I realize this may not be the best practice, but sometimes it's needed.

Can you actually call the now-private method in that case?  In my
opinion, private methods are not part of the API, so they should not be
documented.  In this edge-case, I'm not sure what the status of the
method is.  (I'm ignorant about lots of fiddly ActionScript details like
this -- please tell me The Way It Is ;)


> 2. It may be useful sometimes to copy definitions for inherited 
> methods/properties rather than linking to them. This could be achieved via a 
> command line switch. If class D inherits from C, which inherits from B, 
> which inherits from A, I'd prefer to have the methods for class D in one 
> page so I can print it, rather than having to check three other classes. To 
> use the MX2004 components as an example, we have UIObject --> UIComponent 
> --> SimpleButton --> Button. The documentation for Button should contain 
> everything, as very few people will dig...

There's a balance to be made between,

 - Learning the API of the class in front of us right now
 - Learning the API of the *system* as a whole

While 'flattening' the API documentation as you suggest will make the
former task easier, I think it will be bad for the second task.

Developers using your API should be encouraged to learn that; to know a
class, you must also know its superclasses.  This involves a little more
upfront effort, but will be a saving in the long run, as that effort
will be shared for all the other subclasses.


On the other hand, the current output really isn't designed for print,
and will obviously be deficient without hyperlinks, etc.  The real
solution to this problem might therefore be to create another,
print-specific output format, with cross-references to page numbers etc.

What do you think?


dave

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