[wp-hackers] Inline documentation
ringmaster at midnightcircus.com
Mon Apr 3 16:07:42 GMT 2006
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 (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:
You can access most WP functions by tacking the function name onto the
base URL, similar to the php.net function reference:
WP files can be referenced similarly:
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:
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.
More information about the wp-hackers