Take the 2-minute tour ×
WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. It's 100% free, no registration required.

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?

share|improve this question
    
@tnorthcutt Thanks for adding Codex, I didn't have enough rep =] –  Workman Feb 15 '11 at 15:28

3 Answers 3

up vote 3 down vote accepted

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.

share|improve this answer
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 Feb 15 '11 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. –  Peter Rowell Feb 15 '11 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 Feb 15 '11 at 15:58

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.

share|improve this answer
1  
Also it is deprecated per docs, but is not deprecated per code (does not trigger explicit deprecated error message). –  Rarst Feb 15 '11 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 Feb 15 '11 at 23:52
1  
@kaiser done [character limit filler] –  Rarst Feb 16 '11 at 7:23

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.

share|improve this answer
    
Have you told to wp-hackers list, or mentioned on trac? –  kaiser Feb 16 '11 at 9:55
1  
@kaiser nope, I do no hang out there... :) –  Rarst Feb 16 '11 at 10:02
    
@kaiser +1 [character limit filler] :) –  kaiser Feb 16 '11 at 10:06

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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