[Adium-devl] Adium documentation

Sun Mar 18 21:29:53 UTC 2007

On 18/03/2007, at 23:18, disposable at infinitenexus.com wrote:

> 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.)

Isn't that what I said? It's at least what I intended...

>
> 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.

We probably think of the term "design decisions" a bit different  
here. What I meant was implementation decisions (which are the way  
the internals are designed) shouldn't be available to headers but  
included in the implementation files. I guess we agree here but just  
didn't understand each other :)

- Ofri

- - - - - - - - - - - - - - - - - - -
http://www.dpompa.com
- - - - - - - - - - - - - - - - - - -

>
> - 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
>
> _______________________________________________
> 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/bc533329/attachment-0001.html>