Amarok architecture page - playlist documentation

[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

What you said does make sense. If the documentation in the code is finished
faster, it would benefit people who look at the code.

Thanks,
Sandeep
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.kde.org/pipermail/amarok-devel/attachments/20110710/76f75fe9/attachment.htm