[Adium-devl] Adium documentation

[Evan Schoenberg]

On Mar 18, 2007, at 5:22 AM, Colin Barrett wrote:

> Perhaps we should move Doxygen documentation into the .h files.

For the public API -- the AIXXXControllerProtocol headers, for  
example -- Doxygen documentation in the .h files probably makes sense  
for the reasons brought up later in this thread: doing so is pretty  
standard, Doxygen seems to prefer it, and it makes understanding of  
the public API by plugin and component authors easier.  Also, header- 
based documentation encourages a divorce between intentionality (what  
the method is supposed to do and return) and implementation (how it  
does it).

I think header-based is very useful for stable APIs which are  
primarily used from outside.

On the other hand, when actually working within the module... say,  
hacking on AIContactController itself... I find it useful not to have  
to flip back to the header file continually to see documentation.  I  
don't know of a good way to resolve that with our current tools;  
optimally, we'd rock Java style and be able to see the docs from  
places they aren't actually present.  It's probably too cumbersome to  
put documentation in both places... though maybe we can do full  
Doxygen docs in the header files and implementation and FYI-while- 
working-in-the-module comments in the implementation files.

So if that sounds agreeable, official policy would be:
(1) Public APIs should be Doxygen-documented in the header files
(2) Implementations should of course always be documented as  
thoroughly as is necessary for code clarity and future understanding
(3) Private classes -- such as components -- should be documented...  
in the implementation, on the basis that the header file is largely  
unused and its the local implementation that mattters? How's that sound?

-Evan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://adium.im/pipermail/devel_adium.im/attachments/20070318/b1fe6d93/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 186 bytes
Desc: This is a digitally signed message part
URL: <http://adium.im/pipermail/devel_adium.im/attachments/20070318/b1fe6d93/attachment.sig>