2.0 Goal: API Docs

[Ian Monroe]

On 9/14/06, Martin Aumueller <aumuell at reserv.at> wrote:
> On Thu September 14 2006 10:46, Jeff Mitchell wrote:
> [...]
> >
> > I think a serious goal for 2.0 should be to have API documentation
> > added everywhere that it belongs, such that we should be able to
> > generate *complete* API documentation automatically.  It'll make
> > things easier for us, easier for new people to help us code, and, dare
> > I say it, help reverse the general view of Amarok coders among the KDE
> > community as hacks.  We all know that we're the best media player out
> > there; world-class programs deserve world-class documentation, and
> > this is the time to do it.
>
> I have to disagree a little: the prime goal should be to write code the
> meaning of which is evident:
> - speaking variable and function names
> - consistent naming
> - don't leave out parameter names in prototypes in header files
>
> This is something that can be kept up to date quite easily as the code
> evolves. However, API documentation that resides in comments will very soon
> disagree with the code.

Comments should say what the function is supposed to do, not how it
does it. If this quickly disagrees with the function, then we have an
API thats quickly changing and hello regression city! Which really I
don't think is the case: Amarok's fast development might hide the fact
that there's plenty of stuff that doesn't get touched much at all
(which is good).

So anyways I really do hope that we can get everyone on board with
commenting code as we go along.

On a related note, I'm going to be at-some-point over-commenting the
DAAP client and server code, for the purposes of my computer science
capstone project. I will be ignoring my own advice about comments
probably.

> Or it is very hard to keep up to date. Thus, I
> suggest restricting this API doc efforts to the absolutely most central and
> important classes, such as MetaBundle.
>
> Another important step for beginners (as well as senior Amarok developers) is
> making Amarok's components more independent from each other. A good example
> of many interdependencies are smart playlists. Cases like this should be
> minimized.

Indeed.