[wp-docs] Writing a Plugin
ringmaster at midnightcircus.com
Wed Mar 9 02:58:41 GMT 2005
Michael D.Adams wrote:
> Examples are probably appropriate, but I think it would be best to
> give them their own section. We really only need a few examples, too:
> an action, a filter, something that takes one or two parameters (see
> below). I suggest we keep the example section _as short as possible_
> and encourage people to ask on the list or the discussion page before
> adding new ones. I see this article mostly as a quick reference for
> people, not a tutorial. (Let me know if I'm being too fascist.)
It should be a referecne, but I doubt "quick" is the word, if only
because there are dozens of hooks to document.
For many hooks it would be helpful to see the format of data that's
passed to and from the hook, so each should have an example. For many,
like the template tag filters, a "See the X hook for an example" would
More importantly, the action hook locations need to be explained
thoroughly. Skippy and I had a discussion on IRC the other day that
could have been avoided entirely if this was documented properly.
(Specifically, where edit_form_advanced is inserted.)
> Speaking of keeping things clean, I'd like to eventually get rid of
> the following sections from [[Plugin API]]:
> #General Guidelines for Plugin Authors
> #Adding Submenus to the Admin Menu
> #Plugin Metadata
> and put them on whatever top level Plugin Development article
> ([[Writing Plugins]], [[Plug in into Plugins]]...).
The content of [[Hacking WordPress]] needs to retitle to [[Writing
Hacks]]. [[Writing Hacks]] needs to include information on writing
actual hacks (it currently does) and stuff like the cache plugin
constant. A new page [[Writing Plugins]] would contain basic howtos (a
couple of sections of Carthik's page, but not the whole thing) and links
to the big sections that don't belong in [[Plugin API]]. [[Hacking
WordPress]] then becomes an introduction into the methods of altering
the WordPress code to suit your needs, and a lead-in to the [[Writing
Hacks]] and [[Writing Plugins]] pages.
We need a big developer function reference, too. Not just for
formatting output, either. There are a lot of useful functions in
WordPress that could obviate reinventing the wheel.
All of these pages need to fall under a new umbrella from the home page,
[[Developer Documentation]]. Expect that the rules would be slightly
different here from the rest of Codex as you delve deeper into it, since
you're not going to be talking to the average user. Hopefully, they'll
realize they're lost and go back to the easily found [[Plugins]], which
isn't linked on the API page currently, and should be.
> And another thing. If anyone's been following
> and can tell whether or not this new multiple parameter capability is
> stable enough to include yet, can you make sure the information gets
> in to [[Plugin API]]?
That issue is insane. This needs coverage badly. It seems to me that
as far as the API reference is concerned this should be stable.
More information about the wp-docs