[asterisk-dev] Feedback requested for future 1.6 API documentation

[Jeff Peeler]

On Sun, Mar 1, 2009 at 11:47 PM, Jeff Peeler <jpeeler at digium.com> wrote:

> Last year in May I authored a document detailing all of the API changes
> from 1.4 to 1.6.0 (doc/api-1.6.0-changes.odt). At that time it was thought
> that we would be able to keep the API frozen for all releases after 1.6.0.
> This rigid requirement has turned out to be too hard to accommodate. The
> plan now is to continue documenting the API changes from one release to the
> next. This decision poses a few questions:
>
> What format should be used? Both the file format and the content layout
> should be considered. I originally chose an OpenDocument text simply because
> it wasn't planned to ever be updated. I encourage everybody to take a look
> at the existing document to get an idea of what might should be included.
>
> Who is going to be responsible for updating the document(s)? If the number
> of changes between releases are small, it might be best to just let one
> person to do it. Or perhaps the developer making the change would also be
> the one to best explain it.
>
> I am also pondering whether or not a script to extract the API differences
> would be a welcome addition. The script could also help enforce the chosen
> format. Whether or not this is worthwhile depends on the above questions.
>
> Thoughts?


To summarize these threads, it appears that most are in favor of using
Doxygen in some fashion. Also, developers in the future will be responsible
as they make the API change to also change the associated documentation. To
get the process flowing, I'll find all the changes from 1.6.0 -> 1.6.1 and
post it on Review Board. I hope posting it will help ensure the exact format
and content expected will stand for all future uses.

--
Jeff Peeler
Digium, Inc. | Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at www.digium.com & www.asterisk.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.digium.com/pipermail/asterisk-dev/attachments/20090303/1350c2c6/attachment.htm