API page: http://api.drupal.org/api/drupal/includes--common.inc/function/drupal_re...
drupal_render_cache_by_query() was a new function introduced in issue #652048: Factor out the caching pattern from forum
The doc that was added there has some problems:
a) Not up to doxygen standards (first line should be a summary, I think maybe that's the only problem but maybe others)
b) As noted in comment #24 on the original issue, it doesn't really explain why someone would want to use this function. Hopefully someone can look at the patch that factored this out of where it was previously used and discern what it's for?
http://drupal.org/files/issues/render_by_cache_0.diff
Comments
Comment #1
albert volkman commenteda) Appears to have been resolved with #1315886: Clean up API docs for includes directory, files starting with A-C
b) It seems that only one core function (forum_block_view()) calls this function. The comment directly above the drupal_render_cache_by_query() call from that function says "Cache based on the altered query. Enables us to cache with node access enabled." Perhaps adding something to the tune of "Enables ability to cache with node access enabled"?
Comment #10
quietone commenteddrupal_render_cache_by_query was removed in #2158003: Remove Block Cache API in favor of blocks returning #cache with cache tags. There doesn't seem a need to document it!
Therefore, closing as outdated. If this is incorrect reopen the issue, by setting the status to 'Active', and add a comment explaining what still needs to be done.
Thanks!