Amarok architecture page - playlist documentation

[Kevin Funk]

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?

-- 
Kevin Funk