code documentation

[Teo Mrnjavac]

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.