Re: 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
___
Amarok-devel mailing list
Amarok-devel@kde.org
https://mail.kde.org/mailman/listinfo/amarok-devel

Re: Amarok architecture page - playlist documentation

[Teo Mrnjavac]

On Thu, Jul 7, 2011 at 22:07, Kevin Funk  wrote:
> Thursday 07 July 2011, Sandeep :
>> 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> 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
___
Amarok-devel mailing list
Amarok-devel@kde.org
https://mail.kde.org/mailman/listinfo/amarok-devel

Re: Amarok architecture page - playlist documentation

[Kevin Funk]

Thursday 07 July 2011, Sandeep :
> 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 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
___
Amarok-devel mailing list
Amarok-devel@kde.org
https://mail.kde.org/mailman/listinfo/amarok-devel

Amarok architecture page - playlist documentation

[Sandeep]

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
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
___
Amarok-devel mailing list
Amarok-devel@kde.org
https://mail.kde.org/mailman/listinfo/amarok-devel