Lack of documentation for libalpm is the main reason why we didn't use it. As far as I'm concerned the libalpm documentation is a joke (http://www.archlinux.org/pacman/libalpm.3.html). We also read in the forums and the pacman website that it was not finalized and it might change.
Well, IMHO looking into pacman's (front-end) source is better than any documentation. However, you are right, we doesn't have full documentation, but have some doxygen stuff here: http://code.toofishes.net/pacman/doc/
You can not expect people to use an API that has no clear documentation and no stable interface that they can count on. And you can not expect a developer to try to figure out an API by scanning mailing lists, at least not this one. If it takes anyone longer to figure out an API than write their own software, well guess what they're going to do.
See configure.ac (and its history in master and maint branch: http://projects.archlinux.org/git/?p=pacman.git;a=summary), and LIB_VERSION=`expr lib_current - lib_age`.lib_age.lib_revision formula. API change is permitted in master (devel) branch only, maint branch is for the current 3.1.x "series". So in fact you can experience API change only between real releases (terminology of configure.ac), so between the alpm libraries shipped with 3.0.x, 3.1.y and 3.2.z. But you can also experience tons of super new features in real releases, so it is also recommended to upgrade your GUI to use them (even if we didn't change syntactically anything in API):-P
Currently I am keeping a close eye on Shaman, http://shaman.iskrembilen.com Very promising but hasn't stablized yet.
Regards, Raymano