An API as simple as the command-line client would be as limited as the
command-line client: no error-handling beyond success or failure except
by recognizing error strings (brittle); no complicated information in or
out, such as the information required for a log message, without parsing
strings (complicated and brittle); no fine control over what to do with
informational output.
Really, all you could make with an API like that is a command-line
client, which we have, or a GUI which feels like a thin layer on top of
a command-line client, which we don't want. For a good GUI you want
something more structured.
On Sun, 2002-08-25 at 13:40, Ich selbst wrote:
> I suggest the following changes for the client api:
> - instead of notify funtions and batons just use the notify functions
The baton is a piece of data passed to the notify function. (Other APIs
sometimes call that "userdata".) If we take out the baton, there is no
way to get information to the notify function except through global
variables. Global variables work fine for simple applications, but
don't scale to the complicated ones.
> - handle the apr_pool_t *pool internally
This might be a good idea for libsvn_client, since the interface is very
granular. Unfortunately, if you get an error back, the memory for that
error comes from a pool, and we can't really "handle" that internally.
> - instead of the auth_baton use 'username' and 'password' - thats more
> understandable
But there are more ways to authenticate than by username and password.
> - avoid structs for the api, use the data of the struct directly
Glancing over svn_client, it looks we have a good reason to use
structures in each of the places we do so. (Although I am concerned
about the auth baton; that structure will almost certainly need to grow,
which could affect our ABI.)
> - if you use structs for the api, declare them inside the same header as the
> functions.
Not really practical. And in general, if you don't understand what a
type is, your first questions should not be "what fields does it have?"
but "what is it for" and "how do I make and manipulate it?" Those we
can answer without a declaration in the same header file.
> If everyone who wants to write a GUI for using Subversion needs to dig deep
> and deeper into the subversion source
Here we agree; you should not have to look at the source code to write a
client. For the most part, the combination of HACKING and the comments
in svn_client.h should make things clear enough to write code; where it
doesn't, complain specifically.
(In an ideal world, we would have more comprehensive API documentation;
perhaps a man page for each function. But what we have now isn't really
so bad.)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Aug 25 21:01:47 2002