[Kde-pim] pimlibs documentation cleanup

[Mark]

On Mon, May 21, 2012 at 8:21 PM, Mark <markg85 at gmail.com> wrote:

> 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
>

Anyone interested at all?
_______________________________________________
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/