[Adium-devl] Adium documentation

[Ricky Hussmann]

Just wanted to throw my thoughts into the arena as well, since Michael's
email reminded me of it. I've typically viewed the Doxygen docs as useful
for people that are using the code as an external library, not necessarily
the developers. Its also great for approaching the code at a high level: you
can more easily get a top-down understanding of the architecture and data
flows.

However, using Doxygen doesn't prevent the developer from adding non-Doxygen
comments to implementation files, and as a matter of fact, most people do
this anyway. So, I would suggest packaging the Doxygen markup into the
header files. This would help plug-in developers with ready access to the
docs, and any new folks that are trying to get a general, top-down
understanding of the code. Once the interested party has a better feel for
the overall design they can dig into the implementation files to see the
more detailed comments about the implementation.

While this doesn't really address Micheal's point of documenting structs or
enums, its still a good rule of thumb.

On 3/18/07, Michael Dippery <mdippery at bucknell.edu> wrote:
>
> 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.
>
> _______________________________________________
> Adium-devl mailing list
> Adium-devl at adiumx.com
> http://adiumx.com/mailman/listinfo/adium-devl_adiumx.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://adium.im/pipermail/devel_adium.im/attachments/20070318/615b6e91/attachment-0001.html>