[MOBY-dev] Martin's comments on the MOBY API docs
Frank Gibbons
fgibbons at hms.harvard.edu
Thu Sep 1 13:59:14 UTC 2005
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
More information about the MOBY-dev
mailing list