code documentation

[Teo Mrnjavac]

On Thu, Aug 28, 2008 at 5:40 PM, Teo Mrnjavac <teo.mrnjavac at gmail.com> wrote:
> On Thu, Aug 28, 2008 at 1:26 AM, Jeff Mitchell
> <kde-dev at emailgoeshere.com> wrote:
>> 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
>
> In the beginning I had trouble with TagDialog and TagGuesser, as I
> understand it's pretty old code made by former contributors, and parts
> of it were taken from JuK. By now, after many hours of scratching my
> head I mostly figured out how to make things work (without necessarily
> knowing what does the code do), but sometimes I still find myself lost
> in a sea of nameless strings. There seems to be also some unused code
> there. Another area that I would like to be documented better is
> sqlcollection.
>
Also PlaylistWidget and PlaylistGraphicsView and the stuff around it
would be nice to have documented.