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

[Russell Bryant]

On Mar 2, 2009, at 9:27 AM, Olle E. Johansson wrote:

> All dev docs are in doxygen, so I would suggest that we add another
> "fake" include file that we add this info to, or just add another tag
> in Doxygen that Doxygen will summarize on one page, like \todo's. Then
> we can add information in the file we are changing and will have a
> summary automatically.


Using doxygen gets my vote.  It is really quite easy to use, and seems  
like an appropriate place to do it, so that the documentation of API  
changes is integrated into the documentation of the API itself.

As oej refers to, if you take a look at the "fake" header that we  
have, include/asterisk/doxyref.h, you'll see a number of things that  
we have done to use doxygen for more general documentation bits.

I think we should create an include/asterisk/doxygen/ directory so  
that we can start breaking up the "other" documentation into multiple  
files.  I would suggest a file per release (API changes from 1.4 to  
1.6.0, 1.6.0 to 1.6.1, 1.6.1 to 1.6.2, etc.).

--
Russell Bryant
Digium, Inc. | Senior Software Engineer, Open Source Team Lead
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: www.digium.com & www.asterisk.org