Re: API documentation, was Re: Web services revisited

[Chris Travers <..hidden..>]

On Tue, May 22, 2012 at 8:41 AM, Nigel Titley <..hidden..> wrote:
> 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?

Yes.  See doc/database

Also inside the database definition files you will see a lot of
COMMENT ON statements which are used to generate this information.
Right now the schema files themselves and the HTML autogenerated
documentation are the places to look.  The dia files are ones which we
haven't been able to organize well enough yet.  Suggestions are
welcome here.
>
>> 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?

Yes.  The new code files have extensive POD.  And after you run make,
it generates man pages in blib/man3/ for each Perl module.  Maybe
these should be a download of their own?


Best Wishes,
Chris Travers