Summary:	ASTERISK-04307: Guidelines for Doxygen documentation
Reporter:	Matthew Nicholson (mnicholson)	Labels:
Date Opened:	2005-05-31 12:47:39	Date Closed:	2008-01-15 15:36:48.000-0600
Priority:	Trivial	Regression?	No
Status:	Closed/Complete	Components:	Documentation
Versions:		Frequency of Occurrence
Related Issues:
Environment:		Attachments:	( 0) README.doxygen
Description:	Here is a README file that contains guidelines for properly documenting Asterisk code.  I have seen various incorect and incomplete doxygen constructs throughout the Asterisk code base.  Hopefully this file will help rectify some of that.
Comments:	By: Michael Jerris (mikej) 2005-05-31 12:50:54 Thank you.. this is well needed.  Do we want to put this right into the coding guidelines with notes on what should be documented using doxygen? By: Clod Patry (junky) 2005-05-31 13:15:14 Btw, we should have doxygen docs for almost all functions. By: Olle Johansson (oej) 2005-05-31 15:31:14 Disclaimed? :-) Good work, really needed! By: Olle Johansson (oej) 2005-05-31 15:32:46 Maybe we should add that *all* global functions needs doxygen. The static functions do not need it today. If I remember correctly we are processing all .h files in include/asterisk today, but might want to expand that. Any ideas? Would be cool to have Doxygen docs for Anthms new reference channel :-) By: Matthew Nicholson (mnicholson) 2005-05-31 18:31:34 Maybe I should have just put disclaimer as 'yes', but I work at digium, so everything I do is disclaimed.  I'll just put 'yes' next time. I think we are scanning all source files (*.c and *.h) for documentation at this time.  Feel free to edit the file however you need it.  I have just been trying to use the documentation, and what usually ends up hapenning is me rewriting portions of it (as I did with astobj.h).  I have partial rewritten documentation for module.h and channel.h but there are a few more things to do, I'll post them when I am finished. By: Olle Johansson (oej) 2005-06-01 01:13:26 (There was a smiley after the question about disclaimer, see?) Let's get this into CVS and continue working with it when we have new information and updates. By: Kevin P. Fleming (kpfleming) 2005-06-02 15:36:17 Committed to CVS HEAD, with mods (spelling fixes, clarifications and some additional guidelines). Thanks! By: Matthew Nicholson (mnicholson) 2005-06-02 17:25:30 Just a question.  Why do we have the sentences starting with lower case letters? Like in the case of \return: \return zero on success, -1 on error. Will come out in the html file as Returns:   zero on success, -1 on error. Just wondering why you decided this. By: Kevin P. Fleming (kpfleming) 2005-06-02 17:27:58 I do that since it's not really a sentence... if the description provided to \return was actually a normally formed sentence (like what we do for \brief), then that sort of capitalization would make sense. Same thing goes for \param descriptions, which are usually sentence fragments. Make sense? By: Matthew Nicholson (mnicholson) 2005-06-02 17:55:15 Ok, yeah makes sense.  Gotta go back an change some of my docs now.  Another question.  If it is a complete sentence, is it ok then to start with a cap? By: Matthew Nicholson (mnicholson) 2005-06-02 17:55:57 Another note.  If it is not a sentence, do we still need the periods? By: Kevin P. Fleming (kpfleming) 2005-06-02 18:06:43 Your call on the trailing periods... I don't care much either way. I'll close this one again... if you have any more specific questions about this, let's do it off-line and incorporate the results into CODING-GUIDELINES. By: Digium Subversion (svnbot) 2008-01-15 15:36:48.000-0600 Repository: asterisk Revision: 5818 U   trunk/doc/CODING-GUIDELINES ------------------------------------------------------------------------ r5818 | kpfleming | 2008-01-15 15:36:48 -0600 (Tue, 15 Jan 2008) | 2 lines add guidelines for doxygen documentation writing (bug ASTERISK-4307, with mods) ------------------------------------------------------------------------ http://svn.digium.com/view/asterisk?view=rev&revision=5818