[Adium-devl] Adium documentation

[Michael Dippery]

I guess I'll chime in, since I approached Colin about documentation  
in the first place. :)

I started cleaning up the documentation for Adium, since, if I  
recall, this was something that had been talked about, but not a lot  
of people are working on (and for good reason, it's not nearly as  
much fun as coding, and fixing bugs and adding features is more  
important to the end-user). However, I thought it'd be useful to  
clean it up, especially since Adium seems to be attracting new  
developers (and is hoping to clean up the plugin architecture a bit).

I can understand the reasoning for putting documentation in the  
implementation files, although I think it opens up a number of issues:

1. Doxygen doesn't like documentation for a single class to be spread  
among different files. It complains, and doesn't always generate  
documentation properly. This causes problems in the event that all  
the class methods are documented in the .m files, but then items like  
instance variables, enums, structs, defines, etc., which are only  
defined in the header files, are also documented. It makes a lot of  
sense to include such documentation, though: Since the header file is  
imported by other modules, what seems to matter is the stuff in the  
header, not necessarily the implementation (which can include a lot  
of private stuff, etc.).

2. As noted by Patrick, plugin developers are concerned primarily  
with the headers, not the implementation files, so they're probably  
reading the headers and have little need to open the implementation  
files most of the time.

3. For items that are intended to be distributed as frameworks, or  
things like Sparkle for which only the framework (not the source) is  
included with the Adium trunk, we can only document the header files  
anyway (and it's often the case that third-party frameworks already  
provide documentation in the headers). When documenting, I prefer to  
remain consistent, rather than having some documentation in header  
files, and some documentation in implementation files.

That's my $0.02, for what it's worth. Of course, I'd happily document  
the source in whatever style the rest of the Adium team prefers. :)  
Just so long as it's done in an efficient and helpful manner!


-- Michael


On Mar 18, 2007, at 2:10 AM, Patrick Gibson wrote:

> As a plugin developer I'd like to chime in my $0.02 and say that the
> documentation is best placed the header. It's kinda annoying to have
> to have the Adium Xcode project open along side a plugin project I'm
> working on, just to read the docs.
>
> Sincerely,
> Patrick G.