[asterisk-dev] [Code Review] Doxygen API Changes for 1.6.0 -> 1.6.1

[Russell Bryant]

-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
http://reviewboard.digium.com/r/190/#review533
-----------------------------------------------------------



/branches/1.6.1/include/asterisk/app.h
<http://reviewboard.digium.com/r/190/#comment1251>

    Remove the trailing whitespace before commit



/branches/1.6.1/include/asterisk/app.h
<http://reviewboard.digium.com/r/190/#comment1252>

    Thanks for using the input/output specifiers.  I think this is something we should all make a habit of doing from now on!



/branches/1.6.1/include/asterisk/app.h
<http://reviewboard.digium.com/r/190/#comment1253>

    Hm ... is it really a good idea to have "\since 1.6.1" for API calls that didn't actually change in 1.6.1?  Would it be better to not have it at all?



/branches/1.6.1/include/asterisk/channel.h
<http://reviewboard.digium.com/r/190/#comment1254>

    There is another doxygen method for documenting specific return values:
    
    \retval 0 success
    \retval -1 error



/branches/1.6.1/include/asterisk/heap.h
<http://reviewboard.digium.com/r/190/#comment1255>

    Argh!  I have really got to break this \arg vs. \param habit.  I always think \arg for argument ...


- Russell


On 2009-03-09 14:10:27, Jeff Peeler wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> http://reviewboard.digium.com/r/190/
> -----------------------------------------------------------
> 
> (Updated 2009-03-09 14:10:27)
> 
> 
> Review request for Asterisk Developers.
> 
> 
> Summary
> -------
> 
> This is a continuation of the API changes documentation started for describing changes between releases. Most of the API changes were pretty simple needing only to be brought to attention via the new "Asterisk API Changes" list. However, if you see anything that needs further explanation feel free to supplement what is there. The current method of documenting is to add (in the header file): \version <ver number> <description of changes> and then to add the function to the change list in doxyref.h on the AstAPIChanges page. I also made sure all the functions that were newly added were tagged with \since 1.6.1. I think this is a good habit to start both for the historical aspect as well as for the future ability to easily add a "New Asterisk API" page.
> 
> There were two common bad practices that I tried to fix as I progressed. The first was use of \arg instead of \param. While this practice doesn't break anything, \arg is really for presentation formatting. Also, \param will check to make sure the documentation matches the function declaration. The second mistake was using Doxygen commenting with the function definition instead of the declaration. Doxygen seems to favor extracting the comments from the function definition, which means some of the additional documentation included in the header files was lost in certain cases.
> 
> At this point I'm assuming the chosen format is fine for everybody, so speak up quickly if this is not the case.
> 
> 
> Diffs
> -----
> 
>   /branches/1.6.1/include/asterisk/app.h 179537 
>   /branches/1.6.1/include/asterisk/astobj2.h 179537 
>   /branches/1.6.1/include/asterisk/audiohook.h 179537 
>   /branches/1.6.1/include/asterisk/callerid.h 179537 
>   /branches/1.6.1/include/asterisk/channel.h 179537 
>   /branches/1.6.1/include/asterisk/config.h 179537 
>   /branches/1.6.1/include/asterisk/datastore.h 179537 
>   /branches/1.6.1/include/asterisk/devicestate.h 179537 
>   /branches/1.6.1/include/asterisk/dlinkedlists.h 179537 
>   /branches/1.6.1/include/asterisk/dnsmgr.h 179537 
>   /branches/1.6.1/include/asterisk/doxyref.h 179537 
>   /branches/1.6.1/include/asterisk/dsp.h 179537 
>   /branches/1.6.1/include/asterisk/enum.h 179537 
>   /branches/1.6.1/include/asterisk/event.h 179537 
>   /branches/1.6.1/include/asterisk/extconf.h 179537 
>   /branches/1.6.1/include/asterisk/heap.h 179537 
>   /branches/1.6.1/include/asterisk/http.h 179537 
>   /branches/1.6.1/include/asterisk/linkedlists.h 179537 
>   /branches/1.6.1/include/asterisk/lock.h 179537 
>   /branches/1.6.1/include/asterisk/logger.h 179537 
>   /branches/1.6.1/include/asterisk/manager.h 179537 
>   /branches/1.6.1/include/asterisk/pbx.h 179537 
>   /branches/1.6.1/include/asterisk/res_odbc.h 179537 
>   /branches/1.6.1/include/asterisk/rtp.h 179537 
>   /branches/1.6.1/include/asterisk/sched.h 179537 
>   /branches/1.6.1/include/asterisk/taskprocessor.h 179537 
>   /branches/1.6.1/include/asterisk/tcptls.h 179537 
>   /branches/1.6.1/include/asterisk/timing.h 179537 
>   /branches/1.6.1/include/asterisk/udptl.h 179537 
>   /branches/1.6.1/include/asterisk/utils.h 179537 
>   /branches/1.6.1/main/devicestate.c 179537 
>   /branches/1.6.1/main/enum.c 179537 
>   /branches/1.6.1/main/tcptls.c 179537 
> 
> Diff: http://reviewboard.digium.com/r/190/diff
> 
> 
> Testing
> -------
> 
> Building the documentation via "make progdocs" seems to produce fewer warnings, but that wasn't the primary focus right now. I think I'm a good candidate to fix the remaining errors and will do so in the future. I also checked all the functions that had changed to make sure Doxygen was extracting the comments from the right place.
> 
> 
> Thanks,
> 
> Jeff
> 
>