[wp-hackers] Inline documentation

[Owen Winkler]

Andrew Krespanis wrote:
> Nothing new to add, other than +1 for inline docs.
> I'll happily volunteer to contribute to inline docs and have made an
> account at Owen's existing function reference[1] (though I am unable
> to find a way of editing existing entries...)

For the edification of anyone interested, since I had yet to make this 
project truly public:

I created a developer function reference for functions in WordPress. 
This function reference is located here:

http://redalt.com/fn/

You can access most WP functions by tacking the function name onto the 
base URL, similar to the php.net function reference:

http://redalt.com/fn/the_content

WP files can be referenced similarly:

http://redalt.com/fn/file/functions.php

Only users who are logged in can modify entries.  MicroWiki handles the 
logins at RedAlt, which unifies the logins for the Plugin Version 
Service, the function reference, and the wiki.

You can log in or register a new login pretty easily:

http://redalt.com/wiki/DoLogin

The required email address (for sending out the initial password) is 
just a quick barrier against spammers.  I don't have any intention of 
even looking at the email addresses.

Assuming you've created a login, you should be able to log in to the 
wiki from any function reference page by clicking the small [log in] 
link at the bottom of the page.

After you're logged in, view one of the function reference page.  Click 
on the thing you want to edit.  Edit it.  Easy.

Each item that gets a description usually has 2 description fields. 
Only the short (first) description is used when generating the PHPDoc at 
the bottom of the page.  I have copied some of the Codex documentation 
(the examples, usually) into the detailed field, but not much.

Currently, all plugin hook names are linked to MarkJ's hook directory. 
Also, WP functions in the source link to their reference pages.  I would 
consider generating other types of links if they're useful, like linking 
native PHP functions to their php.net reference.

The function list in the database is updated twice per day by running my 
update script against a fresh svn update of WP's trunk.  The only thing 
that really throws it off is when a function moves to a different file 
(like functions in the new deprecated.php file), in which case more than 
one function might be listed under the same name in the database.  It's 
not as easy to detect these changes as you might think, so for the time 
being, both copies remain referenced.  That makes it possible to copy 
the old documentation to the new function location.  I should make a way 
to mark one instance for deletion after its data has been transferred.

In any case, you can directly reference any function by a unique number 
assigned by the system.  If you poke around the reference site, you'll 
notice this, especially with functions in the importers, which are all 
named the same, but exist in different files.

I currently get email updates when the reference changes via edits and 
via svn updates.  This might be useful for a general mailing list, but 
I'll have to clean it up a bit if the public wants to consume it.

Assuming the system is adopted, my future plans include generating a 
unified diff of the PHPDoc comments that merges cleanly into the SVN 
from which the data is generated.  That way, you would be able to 
download a clean copy of the WP source, patch the latest comments in, 
and then use your favorite PHPDoc-aware editor without having to hit 
RedAlt for the docs.  Of course, the patch would only include the short 
descriptions, but the @link PHPDoc directive should take you directly to 
the complete function reference at RedAlt.

Upon a WP release, we should be able to create an archive of the current 
docs that you could patch into that version.

I'll happily consider any suggestions.  Adding a commenting feature is 
probably not a bad idea, as long as the comments are more oriented 
toward using the functions, and not asking questions about them.  It 
should be more like the php.net function reference, and so comments will 
likely have to be heavily moderated.

Thoughts?

Owen