code documentation

[Jeff Mitchell]

Dan Meltzer wrote:
> On Wed, Aug 27, 2008 at 2:03 PM, Lydia Pintscher
> <lydia.pintscher at gmail.com> wrote:
>> Heya :)
>>
>> As you might know I had a talk with our SoC students at Akademy about
>> what we need to improve in Amarok to make it easier for new people to
>> join development.
>> A few things came up. (See my blog for more.)
>> The biggest problem seems to be lack of documentation in the code. So
>> I have been thinking about ways to improve this. It is necessary not
>> only for new contributors but also to reduce the bus factor of our
>> codebase. Currently I have the feeling it is lower than is healthy for
>> us.
>>
>> So here is what I came up with:
>> 1) I would like to ask everyone to documents the 5 to 15 (the more the
>> better of course) most obscure/difficult functions/classes/... he is
>> working on in the next 2 weeks. I think this is a reasonable number
>> and will get us a long way towards making coding on Amarok
>> easier/futureproof.
>> 2) All the SoC/K students get their code documented as well as
>> possible if they havn't already. (Especially Daniel since the stuff he
>> does seems to be not so easy to gasp for others ;-))
>>
>> Since I know that a lot of you are so used to the code that they don't
>> see what is difficult I would also like to ask the students to name
>> the functions/classes/... they had the biggest problems with.
> 
> http://techbase.kde.org/Development/Tutorials/API_Documentation will
> probably be helpful :)
> 

Another suggestion: if SoC students (or anyone else) want particular
functions documented because they can't figure it out, they should poke
the mailing list or whoever is listed in svn blame.  That way, functions
people are using can get documented as needed, instead of waiting until
the developer gets around to it (if ever).

--Jeff