[Adium-devl] Adium documentation

[disposable at infinitenexus.com]

Although it means more work I fall into favoring a dual approach -  
verbose headers that plugin devs will find useful (in actuality this  
likely falls within a scope of certain classes, not the entire  
codebase) with plenty of documentation in the implementation files  
(all of the codebase) that lists notes about design decisions,  
gotchas, etc. and provide clarity into the working of the method.

- brian 'bgannin' ganninger

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

> Hrm. Does anyone else (Brian? Evan?) have feelings either way?
> Patrick's point about this making lives harder for plugin developers
> is a good one.
>
> Perhaps we should move Doxygen documentation into the .h files.
>
> -Colin
>
> On Mar 17, 2007, at 11:10 PM, Patrick Gibson wrote:
>
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA1
>>
>> 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. ~ PGP Public key ID: 126B7A56
>>
>>
>> On 17-Mar-07, at 9:24 PM, Peter Hosey wrote:
>>
>>> On Mar 17, 2007, at 17:19:12, Colin Barrett wrote:
>>>> Usually documentation is put in header files because the
>>>> implementation will be closed-source.
>>>
>>> Usually the documentation is in the header files because the API is
>>> in the header files, and the documentation goes with the API. This
>>> is what Growl does.
>>>
>>> Having the docs in the .m files puts lots of implementation code in
>>> between runs of documentation, which makes the documentation hard
>>> to read (which has the side-effect of making it more important to
>>> adhere to Doxygen rules so that Doxygen HTML can be generated,
>>> since that's the only way to effectively study the API without
>>> constantly scrolling past bunches of implementation).
>>> ___________________________________
>>> \ Peter Hosey / boredzo at adiumx.com
>>> PGP public key ID: C6550423 (since 2007-01-01)
>>>
>>>
>>> _______________________________________________
>>> Adium-devl mailing list
>>> Adium-devl at adiumx.com
>>> http://adiumx.com/mailman/listinfo/adium-devl_adiumx.com
>>
>> -----BEGIN PGP SIGNATURE-----
>> Version: GnuPG v1.4.5 (Darwin)
>>
>> iD8DBQFF/NfPjipUTRJrelYRAuswAJwMkFHyImBL+heNjqp8cRjd9ELclgCgn7y4
>> h4UC2o1mob6oxst7ky3/XMo=
>> =A+y7
>> -----END PGP SIGNATURE-----
>>
>> _______________________________________________
>> Adium-devl mailing list
>> Adium-devl at adiumx.com
>> http://adiumx.com/mailman/listinfo/adium-devl_adiumx.com
>
>
> _______________________________________________
> 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/5d0379ce/attachment-0001.html>