Add inline documentation to MultiSite functions

[scribu]

Many of the MultiSite specific functions have no inline documentation at all. For example, all those in wp-includes/ms-blogs.php

[hakre]

Any patch in sight? September is closing ...

[scribu]

This would be one of those tickets where patches are extremely welcome.

[scribu]

PS: We don't have to do it all in one go.

[scribu]

I also found this: ​http://codex.wordpress.org/WPMU_Functions

[andrea_r]

Someone point me to whatever is used to format the inline docs & how-tos. Any guidelines?

[nacin]

How's this for a boilerplate template. My comments to the comments are after #.

/**
 * A one-line description of the function
 *
 * A longer description of the plugin. This can span multiple lines.
 * Also might not be necessary. Lorem ipsum.
 * Lorem ipsum.
 *
 * And multiple paragraphs.
 * Lorem ipsum.
 *
 * @since MU # or 3.0.0 etc.
 * @access private # if it is an internal function
 *
 * @param string $argument_name This argument does blah.
 * @param array $args This accepts a whole bunch of args:
 *  - blah_id: The id of the blah. Defaults to false, which means no ID is used.
 *  - foo: The foo. Very important. Defaults to an empty string.
 * @param bool $optional_argument Optional. Default true. This argument does blah.
 * @return array Returns an array of blah.
 */
function my_function( $argument_name, $args = array(), $optional_argument = true ) {
    // Blah
}

[filosofo]

They're phpdoc tags. Here's a tutorial: ​PHPdoc tutorial

[boonebgorges]

I'm working through ms-functions.php and will have a diff in a little while.

[boonebgorges]

14953-1.diff is a start on documenting ms-functions.php. Can't do more now, eyeballs are bleeding.

[scribu]

I've done ms-blogs.php. See ms-blogs.diff

[scribu]

For @since, I just used 3.0.0

[nacin]

(In [15675]) Some phpdoc for ms-functions.php. props boonebgorges. see #14953.

[simonwheatley]

Go on then, I'll bite: docs for switch_to_blog (inc beware, see #14992) and restore_current_blog

[simonwheatley]

Alternative diff, this time with @uses for all functions called within the documented function, is this best practice to list them exhaustively or only where a comment on usage is required/given?

[hakre]

I suggest to put the wordpress version number to ​@since (Documentation), as @since documents when (at which version) an element was first added to a package.

The file changed in r15675 have the following package phpdocs:

 * @package WordPress
 * @subpackage Multisite

The last commit did use the MU version number (prefixing it with MU) which is needlessly inventing something new on top of PHPDoc and breaks with the documentation standard and with the current doing everywhere else in the project. Everywhere else is with a very few exceptions, a related case where this is problematic is here: #14921.

As we do not need to do documentation work for the past of the MU fork (the MU fork is as much as I know history), I suggest to change the @since tags to @since 3.0.0 to streamline them with the rest of the codebase.

Let me know if you would like to have a patch.

[hakre]

Related: #14953

[hakre]

Related: #14783

[nacin]

Replying to hakre:

The last commit did use the MU version number (prefixing it with MU) which is needlessly inventing something new on top of PHPDoc and breaks with the documentation standard and with the current doing everywhere else in the project. Everywhere else is with a very few exceptions, a related case where this is problematic is here: #14921.

As we do not need to do documentation work for the past of the MU fork (the MU fork is as much as I know history), I suggest to change the @since tags to @since 3.0.0 to streamline them with the rest of the codebase.

Boone went above and beyond in tracking down individual MU versions. By no means is that necessary. However, us using @since MU originated in 3.0, and I want to continue that pattern. (That's why I haven't committed scribu's patch yet.) This is a special case. I believe it is important for us to differentiate whether MS functions were introduced after the merge, or whether they were a product of the merge.

---

Simon, patches don't trigger comment notifications, so I'm only seeing your patches now.

Normally there's no need to document every single function via @uses, or even some of them. However, switch_to_blog() and restore_current_blog() need some serious documentation on exactly what they do and what they don't do, ref #14992 and #14941 in particular. We don't need to do little ones like did_action() but for others, it would help to not only include them but to have a description on how said function is used.

[boonebgorges]

14953-2.diff finishes off ms-functions.php.

[jacobsantos]

​http://codex.wordpress.org/Inline_Documentation

Columns should break at either 80 or 100 for consistency with the rest of WordPress. Long Descriptions should be Informative paragraphs with concise information related to the technical details and additional information that couldn't be fit in the short description.

However, more or less, one could go through and edit the files for consistency after they are complete.

[scribu]

Replying to boonebgorges:

14953-2.diff finishes off ms-functions.php.

We should remove all those @uses because:

• they get stale really fast
• you can get that information by using PHPXref or just looking at the source

[scribu]

Set @since MU. More warnings on switch_to_blog()

[scribu]

See ms-blogs.2.diff

[scribu]

Replying to scribu:

We should remove all those @uses because:

• they get stale really fast
• you can get that information by using PHPXref or just looking at the source

As the Codex says, @uses should only be used for globals, like $wpdb.

[jacobsantos]

Replying to scribu:

Replying to scribu:

We should remove all those @uses because:

• they get stale really fast
• you can get that information by using PHPXref or just looking at the source

As the Codex says, @uses should only be used for globals, like $wpdb.

The codex does not say that. It also wouldn't be true in any case. The only reason the @uses would be stale is if there were modifications to the code without updating the inline documentation.

Using a separate application takes away from the reasons behind phpdocumentor sites. I would say that only functions that provide more information on the usage of the function should be linked with @uses as some functions and methods are helpers for other functions.

[scribu]

You're right, I misread.

I would say that only functions that provide more information on the usage of the function should be linked with @uses as some functions and methods are helpers for other functions.

Agreed.

[scribu]

(In [15676]) Add inline documentation for ms-blogs.php. See #14953

[hakre]

Replying to nacin:

Boone went above and beyond in tracking down individual MU versions. By no means is that necessary.

and then:

However, us using @since MU originated in 3.0, and I want to continue that pattern. (That's why I haven't committed scribu's patch yet.) This is a special case. I believe it is important for us to differentiate whether MS functions were introduced after the merge, or whether they were a product of the merge.

Can you please explain me if it is not necessary to document the MU versions, why you believe those are important? I have problems to understand that.

[scribu]

To clarify, * @since MU is fine.

[scribu]

Specifically, still needing dock-blocks are functions in ms-functions.php after around line 500.

[jane]

Freeze hits on November 1, so whatever's left should be posted asap.

[jane]

Beta. Punting. Marking 3.2-early.

[westi]

Replying to boonebgorges:

14953-2.diff finishes off ms-functions.php.

Looks like this never got committed.

[westi]

That patch may need refreshing but has alot of good docs from boone :-)

[SergeyBiryukov]

I've updated the patch from boonebgorges for the current trunk. Should also @uses entries be removed, like scribu suggested? Or should they be revised to include only the most important ones?

[nacin]

Common and utility functions can be removed. Some are certainly useful to reference.

[SergeyBiryukov]

Refreshed the patch to leave out mentions of get_site_option(), site_url(), etc.

[SergeyBiryukov]

Can this go into 3.1 before it needs refreshing again? :) No functionality changes here anyway.

[scribu]

Patch looks good.

[nacin]

(In [17218]) Giant chunk of phpdoc for multisite functions. props boonebgorges, SergeyBiryukov. fixes #14953.