[Adium-devl] Adium documentation

Sun Mar 18 21:18:46 UTC 2007

On Mar 18, 2007, at 3:48 PM, Ofri Wolfus wrote:

> It doesn't have to be more work. When there is proper documentation  
> in the headers, comments in implementation files are only needed to  
> explain non-trivial stuff and internal design decisions, meaning  
> not every little bit must have comments. Most of the time,  
> actually, there will be no need for internal comments as the  
> comments in the headers will do the job. Done right, we'll have  
> everything documented once but separated to parts that are more  
> obvious to look at.

I'd disagree here. The API comments in the header should elucidate  
functional intent, parameters, requirements, and any necessities but  
not design decisions.  (AppKit doesn't tell me why they architected  
NSTextView as they did, it tells me how it operates only to the  
degree I need to work [i.e., hit the NSTextStorage for string-level  
control] ... I'd bet they know on the inside though ;) It can be  
logically solved, but it's not documented.)

That does not supplant a coding level insight spelled out in the  
comments of the .m itself. For example, from Growl, the positioning  
code. There's API documentation for it's intended use, but not a  
history of what the coder[s] were thinking when they started coding  
the internals. Thus you create an impedance mismatch because a coder  
walking up to a given piece will have to intuit what went into the  
code beyond what is in the API (and that shouldn't occur when you  
work with the implementation.)

More simply put, there's no valid argumentation for lacking comments  
in an implementation files and no reason for codifying design  
decisions in API documentation IMO.

- brian 'bgannin' ganninger

>

>
> On 18/03/2007, at 21:35, disposable at infinitenexus.com wrote:
>
>> 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
>>>
>>
>> _______________________________________________
>> 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/808ec459/attachment-0001.html>