[MOBY-dev] Martin's comments on the MOBY API docs

[Frank Gibbons]

Martin,

Thanks for your comments on the API documentation. As I think I pointed out 
earlier, at this point all I've done is to take what was in the wiki, clean 
up the HTML a bit, and check it into CVS. I added a few little bits of 
text, put in some links, and did a little semantic markup, but that's it.

>    The first few comments about the registry API:
>
>    * I think that the first page (with a list of methods) should also have
>(even start with) a list of links to objects used by these methods, such
>as a query object.

If this API is to language-independent, then I'm not so sure we can talk 
about objects, unless the Java and Perl implementations agree on it. My 
personal feeling is that what's needed most is high-level, abstract 
description of the overall scheme. A year ago, newbies had to try and put 
together that picture from the Perl code. While I think the Javadoc is 
really good (especially MOSES), the Perldoc still needs work. And even when 
both are as good as we'd like them to be, it's still useful to specify the 
API in language-independent terms. In Perl, there is not "query object" 
only registry/service objects.

>    * I disagree with labelling the deregisteService as depracated. As far
>as I understood, it will be still around for quick resgiter/unregister
>cycle where I am not conceedrn about security (that somebody can
>deregister my service). So from the API point of view it is a normal
>method, not a deprecated one. Mark?

Well, this is marked as 'deprecated' in the wiki, hence it is so marked 
here too. At some point (perhaps v 0.9?) it would be great to have a code 
freeze, in which we could make sure that the docs and implementation agree, 
so that we could have a product that is internally consistent, even as 
development continues. There's even nothing wrong with writing the API as 
we *wish* it to be (some would say that's how it should be done), and then 
trying to code to that. We can release a version in which the documentation 
makes clear what is implemented, and what is 'to-do'.

>    * service protocol "moby" is actually a service category, not a 
> protocol I think

>    * some details have also categories cgi.soap, some not... I suggest to
>remove all cgi and sopa for now (we will have in in the CVS if we need it
>to re-introsduce it later; surely the 'soap' category bring nothing than a
>confusion (isn't it current moby based on soap? - I know how it is, but
>newbies perhaps not)

Yeah, I tend to agree that this is confusing, since only "moby" exists (not 
"cgi" and "soap"). I agree that they should be culled, but since this is 
what was in the wiki, and I didn't know what the development plans were for 
it, I left it in.

>    * I would move definition of a "A MOBY compliant service" to the
>section about services API (here may be just a link to it).  As I said I
>am really concern that these two APIs are (or were before you enter the
>scene) confusing, so make them as separate as possible.

I agree, I'll try to get greater separation between the registry and 
services APIs.

>    * retrieveResourceURLs has a wrong description (something about providers)

I think is still under development - Mark?

>    And the last (but not an unimportant) general comment: the XML-based
>API should be expressed as DTD (which is more preferable in this context,
>XSD is not so human readable).

I think we'll need a volunteer to help us out on that - I've used DTD/XSDs, 
but never written one. Anyone?

>    Also the details about individual tags and attributes are quitel 
> imited now.

Yeah, we really need to beef up the details.

Thanks for your useful comments, Martin. I look forward to more.

-Frank

PhD, Computational Biologist,
Harvard Medical School BCMP/SGM-322, 250 Longwood Ave, Boston MA 02115, USA.
Tel: 617-432-3555       Fax: 
617-432-3557       http://llama.med.harvard.edu/~fgibbons