Kolf: Rumours of its death have been much exaggerated

[Parker Coates]

On Mon, Jul 6, 2009 at 9:50 PM, Albert Astals Cid<aacid at kde.org> wrote:
> A Dilluns 06 Juliol 2009 04:16:57, Ian Wadham va escriure:
>> On Mon, 6 Jul 2009 8:29:00 am Stefan Majewsky wrote:
>> > Am Sonntag 05 Juli 2009 21:24:30 schrieb Michael Pyne:
>> > > I'm assuming the API docs didn't mention that the list would be sorted?
>> > > Unless that was the case it's definitely an application bug, no one
>> > > should ever expect a list to be sorted in any fashion unless the API
>> > > documentation states so.
>>
>> True, the API docs do not mention that and true, the application writer
>> should not expect such a thing.  The problem, from an application
>> writer's point of view, is that some KDE doco is so brief that you have
>> to guess what the library does or conduct an experiment in your code.
>>
>> The trap you fall into then is that you cannot distinguish easily between
>> a feature and a side-effect.  Worse still, if the doco is not good, you may
>> completely miss finding and using a valuable feature.
>>
>> KConfig doco and all KDE doco has improved tremendously since the
>> time Kolf was written, several years ago.  I would like to help make it
>> even better, but there is a Catch 22 ... how can I write about something
>> I do not fully understand?  I would need some expert help to review
>> anything I wrote.
>
> I think that just pointing out were you find some explanation is missing would
> be enough, most of the times one as a library developer does not add more
> documentation because for him it's obvious what the function does, so someone
> pointing what is missing is a very good thing already.

Yeah, I think an email to kde-core-devel should get you a prompt
answer the majority of the time. Also, not all of the KDELibs code is
scary complicated. Sometimes just taking a peek at the implementation
is enough to answer API questions.

Parker