Amarok architecture page - playlist documentation

[Teo Mrnjavac]

On Thu, Jul 7, 2011 at 22:07, Kevin Funk <krf at gmx.de> wrote:
> Thursday 07 July 2011, Sandeep <sandy.8925 at gmail.com>:
>> Hi,
>>
>> The explanation in PlaylistModelStack.h about the playlist model
>> architecture is quite useful. It might be a good idea to include it in the
>> playlist section in this page:
>> http://amarok.kde.org/wiki/Development/Architecture.
>>
>> I also suggest that the following link:
>> http://doc.qt.nokia.com/latest/model-view-programming.html<http://doc.qt.no
>> kia.com/latest/model-view-programming.html#proxy-models> should
>> be added to both the comments in that file and the architecture page since
>> it explains the model-view concepts and proxy models quite well. I was able
>> to understand how the playlist worked a lot better after reading that page.
>>
>> Thanks,
>> Sandeep
>
> Hey there,
>
> First, thanks for the effort of discussing documentation related issues (there
> are quite some) in Amarok, but...
>
> I'm *all* for doing this the other way around:
> Better put the class/architectural documentation into the source code as far
> as possible. Qt does that very heavily and succeeds in providing an
> comprehensive and up-to-date source code documentation as developers are still
> paying attention to it. I'm not really convinced that stuff like that should
> go to a Wiki anyway.
> (You could still link from the Wiki to our apidocs, though).
>
> Reasoning is obvious:
> * Wiki-Documentation quickly gets out of date / out of sync with source code.
> * Long-time involved developers (as me) don't look at / adjust it at all.
>  (I'm pretty sure I'm not the only one here, heh)
>
> Doing inline documentation will also have the positive side-effect that our
> API-docs may get polished sooner or later.
>
> Thoughts?
What Kevin said.
Typing // or /** and then some stuff is way quicker and easier than
editing some wiki page. The time that would be wasted on wiki markup
is better spent coding and documenting inline. There's of course no
problem in generating apidocs from there or even copying it to a wiki,
but documentation in the code should come first.
Cheers,
-- 
Teo