@internal

libs monday, so once i got to coding that's where i headed.

whilst working, i came across a small class that was marked as @internal that was being used in a number of places in kde, though it wasn't necessary in any of them, really. when a class or method is marked with @internal, don't use it. if you must use it, then something is broken and a rational for its use needs to be made and then the problem documented until it can be fixed.

i know that all sounds very obvious, because it is, but ... it evidently still needs to be said =)

on the other side of that fence, if you mark something with @internal see if you can prevent the export of that symbol so others can't stub their toes on using it. if that's not possible, try putting it somewhere that others can get to such as in an uninstalled header or in the implementation itself. sometimes that's not possible because internal subclasses need to get to those symbols; in that case it may be worthwhile to consider marking it with uglyness such as prefixing the name of the class or method with something suitable off putting.

i started doing a header-by-header inspection of libkdecore looking for things like missing dptrs, member variables, inlined methods, etc. i'd really like kdelibs to be as clean as possible in kde4, so it seems worthwhile. unfortunately it became tuesday all to quickly in europe (i'm gmt-7 and had various communications to attend to in the morning). this has left me with:

aseigo@liberty:~/kde4/KDE/kdelibs$ svn diff kdecore/ | wc -l
3083

ugh. i'll have to carry this over to next monday. at least one more class moved into kde3support and out of kdecore in the process (krfcdate, which is completely superseded by kdatetime). i didn't bother going into network since i know thiago is going to raise a storm in there soon, and i still have the kernel, sycoca, text and util subdirectories in kdecore to get through. then i can move on to kdeui, and after that kio.