[Kde-pim] pimlibs documentation cleanup

Mon May 21 19:21:06 BST 2012

Hi,

With KCal i got the (nasty) surprise that it is deprecated! While nothing
in KCal seems to indicate that.
With KABC i got another (yet again nasty) surprise that it should not be
used..

And i'm not even using any of it! I'm only reading through the API docs and
figuring out how to combine some parts to make nice applications. So to
prevent more nasty surprises i would like to cleanup the documentation and
deprecate the API's that should be deprecated. Both in documentation and in
coding.

So the following is a list of all pim components as they currently are in
kdepimlibs.
Lets just see this as a nice effort to get the pimlibs documentation
perfect shape for KDE 5. As much input as possible would be very valuable.
Please do describe each component (if you are going to do that) as if the
text was going to be placed on api.kde.org directly.

Note: i also made a wiki page with the below contents:
http://techbase.kde.org/PIM_Apis I would appreciate it if you could post
your improvement in documentation on the wiki and let it know in this
mailing list.

akonadi
  contact
  kmime

Both don't have any documentation. What are those doing?

kabc

Seems to be deprecated or at the very least not the suggested way to do it.
Recommendations:
add: "KABC should be avoided. Use Akonadi directly."
Deprecate in KDE 4.9 (or 4.10)
Remove in KDE 5

kalarmcal

Seems to be used by KAlarm application. My recommendation would be to
deprecate this in 4.9 or 4.10 and remove it in 5.0, but i know others like
this class.
Keep it as it is?

kblog

What's the status on this?
Keep it as it is?

kcal

Replaced by KCalCore.
Deprecate in 4.9.
Remove in 5.0

kcalcore

Keep it as it is.

kcalutils

Do we need this as a separate API? KCalCore is implementing iCal and vCal
as well so why not add this to KCalCore?
Recommendation: Move functionality to KCalCore
Deprecate in 4.9 (or 4.10)
Delete in 5.0

kholidays

What's the status on this?
Keep it as it is?

kimap

There is this one and the one below here as a kioslave.. The names seem -
at the very least - confusion since both are "imap" stuff.
Some more detailed description as to which one is doing what would be
welcome. My guess (don't know for sure) is that this one is for making a
mail client and the kioslave one is for making shared internet folders..??
More documentation needed.

kioslave

  imap4

More documentation needed. (see comment above from KImap)

  mbox

What is this? It misses any documentation.

  nntp

What is this? It misses any documentation.

kldap

What is this? It misses any documentation.

kmbox

Same story as the mbox in kioslave. And it misses documentation.

kmime

Same story as the mime in akonadi. It has very detailed documentation.
Which one should be used? This one or the one in akonadi?

kontactinterface

It could use some more documentation.

kpimidentities

What is this? It misses any documentation.

kpimtextedit

Keep it as it is.

  richtextbuilders

What is this? It misses any documentation.

kpimutils

>From the limited documentation this seems to belong in one of the mime
classes.
I'm not sure but how about merging those with one of the mime classes and
deprecating this one followed by a remove in kde 5?

kresources

Don't know.. From the documentation (which it has quite extensively) it
seems to be usable for KABC and perhaps KCal - both are not even
recommended to use anymore - and i can't seem to find any trace of this in
KCalCore (from a quick glance) so this class "seems" to be unused.
Difficult to check since lxr.kde.org seems to be dead a.t.m.

I'm not sure, but leaning towards deprecation in KDE 4.9/4.10 and removal
in KDE 5. Some more info on this class would be welcome.

ktnef

Keep it as it is.

kxmlrpcclient

Keep it as it is.

mailtransport

Keep it as it is.

microblog

kblog and kmicroblog. I'm guessing those should be merged with kblog.
Recommendation: Merge with kblog.
Deprecate in KDE 4.9/4.10
Remove in KDE 5

qgpgme

No documentation, no class list at all. Only a file list. Either fix or
remove this one.

syndication

Keep it as it is.

  atom

No documentation.

  rdf

No documentation.

  rss2

No documentation.

Cheers,
Mark
_______________________________________________
KDE PIM mailing list kde-pim at kde.org
https://mail.kde.org/mailman/listinfo/kde-pim
KDE PIM home page at http://pim.kde.org/