Re: API documentation, was Re: Web services revisited

[Nigel Titley <..hidden..>]

On 22/05/2012 16:30, Chris Travers wrote:
> Just a couple quick notes and questions.
>
> The first is that of course when we started, there was no 
> documentation for SQL-Ledger that was freely available except what I 
> wrote.  Everything that we have has been added since the fork.  I 
> think that some of Nigel's complaints are exactly why a web service is 
> needed.  More on this below.

And let me quickly say that I enormously appreciate the work that the 
developers are doing

> What we currently have that's in good shape are:
>
> 1)  Database documentation  (could be better though if someone wants 
> to help arrange the dia files' diagrams).
Can you point me at this please?

> 2)  Perl API documentation for code that was new in 1.3.  (though this 
> isn't as obvious as to where to look as it needs to be).  All new 1.3 
> API's are documented, and we are in the habit of documenting API;s as 
> they are created.  For 1.4, I want to organize what documentation we 
> have in this area into a reference manual.  I would also like to 
> ensure that it gets installed as man pages (why I am working on a make 
> install installation).
Is this documented in the code or elsewhere?
> With web service API's, these too will be documented.
Wonderful.... and I really mean it.
> Part of the legitimate reason for Nigel's frustration is that the old 
> SQL-Ledger API approach was pretty brittle and instead of maintaining 
> that we have been trying to move away from it as quickly as we can.  
> For orders and financial transactions we should be pretty backwards 
> compatible except for authentication (use HTTP basic auth), but these 
> will be moved off to the new framework as soon as we can and then web 
> services will be preferred.  For invoices and orders though this may 
> take a few major versions.

I'm really looking forward to the new framework. My fingers are becoming 
deformed through keeping them crossed that my current ramshackle 
arrangements will keep going.

> For those doing things like this we can always use samples and 
> writeups.  For people who need help with code they have written, this 
> is a good place to ask.
>
> Anyway, just figured I would throw those things out onto the table.
Many thanks again

Nigel