[wp-hackers] Codex function page proposal
wordpress at santosj.name
Sun Dec 28 02:49:27 GMT 2008
I want you guys to pay attention, because this is most likely going to
be a long post and skipping parts will lose information. I would say, it
is a really bad idea, because I know so, but that argument doesn't work
with children, so I doubt it would work with adults.
The problem with function documentation on the codex is even worse than
having it in the source code. At least in the source code, there is a
chance, albeit a slim one that the documentation will be updated when a
change is made. That is problem, most patches I've seen don't bother
updating the comments when the comments should be updated. What makes
you think they are going to take the time to update the codex page either?
You are duplicating efforts. I have committed to keeping the inline
documentation updated, I'm sure as hell not going to duplicate my
efforts for the codex as well. I figure it will take merely a week
before a release, to check to make sure that the documentation is
complete, that any new functions has documentation, and go through and
check and tighten up old documentation. I'm going to extend that time
further by updating the codex as well.
Having the documentation on the codex was good, when inline
documentation was sparse and the function reference didn't exist
(http://phpdoc.wordpress.org/trunk/) I will suggest you link to that for
the parameters, return types, and other information already contained in
the function documentation site.
I would rather see more of http://codex.wordpress.org/Shortcode_API type
pages. Function reference pages are only good when you know what you are
searching for. You have to know that the function exists, before you can
go to it. It is to remind you of information you already know or to give
you more information that doesn't exist elsewhere. It is meant for
programmers, but it is useless to programmers without some companion to
let them know they should be looking for it.
The reason the PHP function reference works, so well, is that it is
written in DocBook and contains codex type information, as well as
function reference type information. There isn't a function reference
for PHP, nor is there a codex (like WordPress has) for PHP. PHP just has
both in one. They don't duplicate efforts, because everyone's effort is
in the DocBook. Therefore, if there is a change, they just do so in one
Whereas for WordPress, you have two places, you already have the
function reference. Therefore, the parameters, return types, and other
miscellaneous function relevant information is known there. For the
Codex, I would rather like to see more examples. There is a reason I
didn't put examples in the inline documentation, I knew the codex was
the best place to put it. It is a place that has many contributors, can
easily be updated, and examples don't need to be changed or updated
often. If examples need to be updated, then a regression has occurred
and it is a defect that needs to be fixed or documented and the example
I figured that the best place to have documentation about parameters,
return types, and other information specific to the function was inline
to the function. I figured the best place to have the examples was in
the Codex. The reason there are sometimes examples in the inline
documentation is that there wasn't a codex page for the function or it
was someone else who thought it would be a good idea.
No, the codex should have more pages like the Shortcode API Codex page.
Actually, there shouldn't really be very many function specific pages
either. It was my hope that the focus would be more on the layman
descriptions explaining the functions and examples on how to use the
functions than on parameters and return types.
I am not much of a writer, I've tried to do this before and it is
terribly boring to me. I haven't even wrote the HTTP API Codex page
either. Really that is my fault, but I mean it isn't that difficult, or
at least it isn't to me.
I've leave you with this gem. If you are not ready to babysit the Codex
parameter and return type information, then no one else is. If you think
for a moment that you will leave the community or abandon the Codex
effort, then don't do it. I think the reason you are doing it, is
because you think programmers pay more attention to the Function
Reference and I'll tell you that they don't. Programmers need good, well
written Codex style documentation as well, no matter the skill level.
The problem is always that function reference lacks context, which
examples provide, however what provides an even greater context is how
other functions go together. In this well, you establish a relationship
and make other functions related to the one known to the developer and
I'll say that Designers need to have some programmer knowledge, so if
they are scared by a little function or whatnot, then they should hire
someone like me, who knows WTF he is doing! That said, any person should
understand the concepts given in an example and explained in detail.
Unless they wish to not understand and in that case, dressing the
verbiage in "designer friendly" terms doesn't seem acceptable to me.
Then again, I'm an asshole, so WTF do I care?
More information about the wp-hackers