[wp-docs] Re: [wp-hackers] Codex function page proposal

[Charles K. Clarkson]

Jacob Santos wrote:

 > What makes you think they are going to take the
 > time to update the codex page either?

I don't think they will. I was really concerned with this as well when I
launched my function reference project. I was also concerned that I
might burn out because there seems to be almost 1900 functions in
WordPress. It's a daunting project.

I hated the idea of having to rewrite much of what was in the inline
docs. I am not a good candidate for boring rote work. I am a writer and
a programmer though and think I might be able to offer more insight and
better descriptions than the inline documentation offers.


 > You are duplicating efforts.

You are not thinking like a programmer.

I started programming too many decades ago and along the way worked a
few years with Perl. I decided to start writing the function reference
by first writing a parser for the inline documentation in the source
code and having it create the Codex documentation for me. I wrote it in
Perl because I develop in it faster than I do in PHP (and because Perl
has awesome quote operators).

I have added 82 new function definitions this month. Some of them mimic
the version 2.7 inline documentation exactly. Others are more robust
because I keep adding new search and replace features to the parser. I
have been working on adding links to the global variables recently and
have added a limited concept search for some of the XML stuff (like
XML-RPC) in the description field.

The script is not ready for public use (yet), but I have been changing
the documentation I produce by adding PHPDoc stuff to my local copy of
version 2.7 and rerunning the parser. I still change some parser
mistakes in the end result, but not as many as a few weeks ago.

One goal is to write a script which will automatically update some
sections of the function reference in the Codex as each new version
comes out. Right now, I could safely update the Usage, Parameters,
Returns, Change Log, and Source File sections of each function in the
reference automatically. (Writing a web bot in Perl is a breeze. It
takes only a few hours to write and test.)

The Notes section would require some tweaking as I have added notes to
the Codex for some functions which do not fit in the PHPDoc inline
documentation tags. Though that limitation could be due to my own
ignorance of PHPDoc tags.

If I can get the hang of editing the inline docs in the WordPress CVS,
then the parser should allow updates to the Codex from the inline
documentation from a script. That should reduce some (or perhaps most) 
of the duplication in maintaining the Codex.

HTH,

Charles Clarkson
-- 
Mobile Home Investor
Free Market Advocate
Programmer

Stephenville, TX
http://www.clarksonenergyhomes.com/wordpress/about/
http://twitter.com/CharlesClarkson
+1 (254) 968-8328