XML-RPC class should have better documentation

[koke]

Right now, most of the comments on src:trunk/wp-includes/class.wp-xmlrpc-server.php are like this one:

	/**
	 * Retrieve page list.
	 *
	 * @since 2.2.0
	 *
	 * @param array $args Method parameters.
	 * @return unknown
	 */

At least they should detail more about the contents of $args and the values returned.

[koke]

Commented some xmlrpc functions

[koke]

This should be an easy (although tedious) task. I've attached a patch commenting some of the functions. This way, the format and expected content of the documentation can be discussed before doing all the hard work

[koke]

Ooops, put the trac link bad: source:trunk/wp-includes/class.wp-xmlrpc-server.php

[josephscott]

Some of this gets tricky, for instance if we allow for custom post statuses, trying to list the valid ones in the comments is going to be incomplete at best. Another challenge is that since most people interested in this API are external clients, they are unlikely to read the source code. In some cases they are forbidden from doing so.

Some of these have already been documented in the codex, and that might be a better place for these overall. The source code comments could link to the codex pages for reference.

[westi]

One of the reasons I want this in the code is so that the expected behaviour is documented with the implementation as this makes it much easier to review changes

[koke]

As an example, bbpress documentation in xmlrpc is quite good:
​http://trac.bbpress.org/browser/trunk/xmlrpc.php#L497

[koke]

More documentation for wp.getComments, wp.deleteComment, and wp.editComment

[westi]

Moving to 3.2 - documentation changes only

Removing GCI as the task was never done for GCI

[westi]

(In [17646]) The beginings of better phpdoc for XMLRPC functions. See #15238 props koke.

[westi]

(In [17647]) More better phpdoc for XMLRPC functions. See #15238 props koke.

[jane]

This has as much as it can get for 3.2, are past freeze. Open new ticket(s) for additional documentation patches in next release.

[nacin]

New tickets for new patches.