(!1711) dix: add in-code docs for dixDestroyPixmap()

Give some more explaination for the dixDestroyPixmap() function.

Signed-off-by: Enrico Weigelt, metux IT consult <info@metux.net>

include/dix.h

@@ -148,8 +148,20 @@ extern _X_EXPORT void UpdateCurrentTime(void);
 
 extern _X_EXPORT void UpdateCurrentTimeIf(void);
 
-extern _X_EXPORT int dixDestroyPixmap(void *value,
-                                      XID pid);
+/*
+ * @brief dereference a pixmap and destroy it when not used anymore
+ *
+ * Despite the name, this function unref's the pixmap, and only destroys it when
+ * the pixmap isn't used anymore. (perhaps it should be renamed to dixUnrefPixmap())
+ *
+ * Note: it's also used as resource destructor callback, hence that strange args.
+ * (not actually finest art, but for now a good compromise, since it's already
+ *  existing and exported, thus can easily be used by drivers, w/o breaking compat)
+ *
+ * @param pPixmap pointer to pixmap (PixmapPtr) that should be unref'ed
+ * @param unused ignored, only for matching the resource destructor prototype
+ */
+_X_EXPORT int dixDestroyPixmap(void *pPixmap, XID unused);
 
 extern _X_EXPORT ClientPtr NextAvailableClient(void *ospriv);