Named category functions/docs need cleaning up

[DrewAPicture]

Spawning from a small discussion in #19776, I think it's about time something is done to deal with the older named category functions such as wp_category_dropdown and wp_list_categories in category-template.php

These functions aren't technically category-only as they accept a set $taxonomy. And because they are actually taxonomy-agnostic, I think we have a few different routes we can take to clean up after ourselves a bit:

A) Lock down these functions to 'categories'-only in favor of new, taxonomy-agnostic ones.

B) Leave the functions alone but let the inline-docs and hard-coded strings such as 'No Categories' reflect their versatility. e.g. 'No Terms' vs 'No Categories'.

C) Deprecate these older functions in deference to newer, taxonomy-agnostic ones.

Sorry, should be #19776. Can somebody modify the description? Edit: Thanks, helenyhou

19780.diff adds wp_dropdown_terms() and wp_list_terms() as wrappers for their respective "category" functions. It doesn't deprecate the existing functions or change their behavior, it just adds the new ones.

The main benefit here is making it easier for people to find the functions that do what they want. For example, when looking for a function to list terms I didn't realize that I could pass a taxonomy to wp_list_categories(), which was frustrating for a while.

Fixes gramatical typos. Props helenyhou

I'd prefer this rewrite to taxonomy-agnostic behaviour to be more complete. Therefor also the filters (like list_cats, wp_list_cats, wp_dropdown_cats) and the filters in the Walker classes should be rewritten to a taxonomy-agnostic style. Additionally 1) the list_cats filter in the Walker classes would do great when sending the $args variable as third parameter and 2) we might not wrap each list item with an <a> tag by default; I could think of use cases where I would want to set a custom href attribute on it or don't use an <a> tag at all (@see Walker_Category::start_el()).

Concerning the wp_dropdown_terms and wp_list_terms solutions, I'd say they'd be better off the other way around, as the base of the category functions instead of the wrapper type like it's suggested in 19780.diff. This would result in wp_dropdown_categories being a wrapper for wp_dropdown_terms etc.