Summary:	ASTERISK-04326: [PATCH] Static function documentation
Reporter:	Matthew Nicholson (mnicholson)	Labels:
Date Opened:	2005-06-02 11:52:45	Date Closed:	2011-06-07 14:11:59
Priority:	Trivial	Regression?	No
Status:	Closed/Complete	Components:	Documentation
Versions:		Frequency of Occurrence
Related Issues:
Environment:		Attachments:	( 0) doxygen_no_static.diff.txt
Description:	I was wondering why we are including static function documentation in the doxygen docs.  I do think the functions should be documented, but should we include these in the API docs? ****** ADDITIONAL INFORMATION ****** The attached patch removes static functions and local structs from the documentation.
Comments:	By: Kevin P. Fleming (kpfleming) 2005-06-02 13:47:44 I made this change intentionally, but it's certainly open to discussion. Either we need to clean up the doxygen docs to _only_ document published, supported APIs, or we document everything and mark some things "for internal use only" (as I already did for the existing static functions that are documented). Personally, I find that using doxygen to document complex functions, even when they are static, is a good thing because it allows developers to look in only one place for documentation, not two (internal and external). By: Matthew Nicholson (mnicholson) 2005-06-02 16:07:47 I agree that every function should be documented, but I don't think every function should be in the documentation, it clutters it up and becomes confusing for some. Maybe there is a way to seperate the non static functions from the static ones.  I will investigate. By: Kevin P. Fleming (kpfleming) 2005-06-02 17:29:49 I would agree if we were actually distributing the docs separately from the sources (via a website or a tarball), then that distributed copy should be only the 'public' APIs. But for documentation made from a source tree, I think it makes the most sense for the doc files to be as complete as possible. If you want to add a Makefile target that builds docs for only 'public' functions, that would be a good addition. By: Matthew Nicholson (mnicholson) 2005-06-02 19:03:26 Ok, that makes sense.  And we don't distribute them like that yet, and if we did we could just change the options for that build.  Go ahead and close this if you want. By: Michael Jerris (mikej) 2005-06-02 19:30:41 If anyone wants to create the makefile patch go ahead and reopen this one when the patch is ready.