0

The function get_users_of_blog() is to be deprecated in WP 3.1.0 but the current production release is 3.0.5.

Does it make since to have the documentation reflect a nightly change when the production version of get_users_of_blog() is still the primary function used to fetch a list of users? Or is it fine so long as the version it is deprecated is listed on the article?

I reverted the page back to reflect that it was not deprecated but it was reverted quickly back to it's original state. I'm probably just missing something and was hoping someone would shed some light on this.

EDIT
@kaiser pointed out that the codex is a wild-west of sorts, some articles are up-to-future to 3.1, up-to-date with 3.0.5, and others are very outdated.

Refocusing my question, what should be the best practice for documentation on a popular framework like Wordpress that does have public nightly builds?

1
  • @tnorthcutt Thanks for adding Codex, I didn't have enough rep =]
    – Workman
    Commented Feb 15, 2011 at 15:28

3 Answers 3

3

The codex is some kind of a mess. General behavior is to let users (re)write it and then go over it and change what they (whoever this is) think. Ex. The Codex lacks a lot of functions in the function reference. On some places you already got the 3.1 explanations, on other completely outdated stuff. Sometimes you'll find two versions (current and future) or existing empty pages for template tags coming in the future.

3
  • 1
    Agreed, the Codex is a mess. Google's generally more helpful when finding more about functions in WordPress, and a lot of the time, WordPress.SE usually makes it to one of the top search results. ;)
    – Zack
    Commented Feb 15, 2011 at 15:39
  • 1
    +1: This was one of my biggest surprises when coming from Django to WP. The docs are in a sad state, updates seem to be completely random, and the people writing them often seem to be confused themselves. I find myself using external sites to discover WP functionality, and then reading the code to discover what is actually happening. Although this is a slow process for myself, it is the Great Wall for people with fewer technical skills. Commented Feb 15, 2011 at 15:46
  • Even if you are more tech savy and read through the source code you sometimes still find undocumented or only slightly documented parts. And +1 for "confusion on editors" :)
    – kaiser
    Commented Feb 15, 2011 at 15:58
3

On get_users_of_blog() we had a question before and the problem is that some of the built_in function still use this function.

So get_users_of_blog is a weird case because looking at the codex, Yes this function is depreciated and you should use get_users() which should be shipped with Version 3.1

but if you look at wp_list_authors ( a built-in function) it uses get_users_of_blog() be itself.

3
  • 1
    Also it is deprecated per docs, but is not deprecated per code (does not trigger explicit deprecated error message).
    – Rarst
    Commented Feb 15, 2011 at 19:56
  • @Rarst: Another mystery... Could you place that as a separate answer, so i could upvote it? It's more than banal and would absolutely be correct as a separate answer.
    – kaiser
    Commented Feb 15, 2011 at 23:52
  • 1
    @kaiser done [character limit filler]
    – Rarst
    Commented Feb 16, 2011 at 7:23
1

It is documented as deprecated in Codex, but it doesn't have explicit _deprecated_function() call in source and is not moved to wp-includes/deprecated.php.

It is clearly case of documentation running ahead of code.

3
  • Have you told to wp-hackers list, or mentioned on trac?
    – kaiser
    Commented Feb 16, 2011 at 9:55
  • 1
    @kaiser nope, I do no hang out there... :)
    – Rarst
    Commented Feb 16, 2011 at 10:02
  • @kaiser +1 [character limit filler] :)
    – kaiser
    Commented Feb 16, 2011 at 10:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.