Wordpress - What Is The Use Of map_meta_cap Filter?

This filter allows you to extend the map_meta_cap() function. This function is called by WP_User->has_cap() to convert a meta capability to one or more primitive capabilities.

For example, you want to know whether the current user should be allowed to edit the current post, the edit_post meta capability. This depends on some factors: is the user the author of the post? Is the post already published? Is the post marked as private? The primitive capabilities are edit_posts, edit_published_posts, edit_others_posts and edit_private_posts: you can assign these to user roles. map_meta_cap() checks the author and status of the post and returns the correct set of primitive capabilities this user must have to allow editing of the post (if the post is written by someone else and published, it would return array('edit_others_posts', 'edit_published_posts'), so the user must have both capabilities to continue).

Adding this idea of meta capabilities and primitive capabilities allows you to keep the base WP_User class free from knowledge of posts and post statuses and whatever, and just focus on capabilities. The actual conversion is in an external function, map_meta_cap().

The filter map_meta_cap allows you to extend the functionality, for example when using custom posts. I believe basic support is provided if you set the capabilities argument of register_post_type, but the mentioned article by Justin Tadlock and Prospress plugin provide complete examples of this. But you can customize it to completely turn the capabilities system over, if you desire.

This filter can be used to map meta capabilities for custom post types. There is a good code sample in this article:

http://justintadlock.com/archives/2010/07/10/meta-capabilities-for-custom-post-types

This is filter of function map_meta_cap(). From description this function seems to write out general capability (can_do_stuff) passed into more specific (if post's author then can_do_this_stuff and can_do_that_stuff_also), checking various conditions if needed.

Unfortunately it is not documented in Codex and I can't find a single direct call of this function in WP 3.0.1 source.

Had you encountered usage of this function or want to use it for something? I assume since it doesn't seem to be used, there are probably newer and better ways for this functionality.