Making the move...

[Mark Wieder]

Marielle-

Friday, March 17, 2006, 4:44:16 AM, you wrote:

> 2) Rich and easy to access documentation

> If you want to use a java library written by somebody else, simple,
> you get access to the API online and you know what method to call and
> how. You don't need to know *anything* about the inner workings of  
> the library. Why is it? Because some some conventions have been  
> created which let you comment your script in a very efficient way,  
> where the API doc can be automatically generated from these comments.
> http://java.sun.com/j2se/javadoc/. There is *NOTHING* even close to
> this in revolution. Here, if you want to find your way through

...sure there is. You have to roll your own, but it's not that much
transcript code. My libraries generate their own documentation through
a javadoc-like mechanism. Check out, for example, my ArchiveSearch
plugin on revonline and open the libDispatcher library. Click on the
API button.

And the ECMI document was developed as a way to provide library
developers with a standardized way of documenting the api, among other
things. If library developers don't follow this then it's no different
from java developers not supplying javadoc comments or providing api
documentation online. They're just conventions that have become fairly
universally adopted. Not knowing *anything* about the internal
workings of a library can cause much more pain in java than in rev,
especially in areas of throwing exceptions and threading.

-- 
-Mark Wieder
 mwieder at ahsoftware.net