WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 3 years ago

#14953 closed enhancement (fixed)

Add inline documentation to MultiSite functions

Reported by: scribu Owned by:
Milestone: 3.1 Priority: normal
Severity: normal Version: 3.0
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:

Description

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

Attachments (8)

14953-1.diff (6.5 KB) - added by boonebgorges 4 years ago.
ms-blogs.diff (7.2 KB) - added by scribu 4 years ago.
switch_to_blog and restore_current_blog inline docs.diff (1.5 KB) - added by simonwheatley 4 years ago.
Go on then, I'll bite: docs for switch_to_blog (inc beware, see #14992) and restore_current_blog
ALT switch_to_blog and restore_current_blog inline docs.diff (2.0 KB) - added by simonwheatley 4 years ago.
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?
14953-2.diff (27.1 KB) - added by boonebgorges 4 years ago.
ms-blogs.2.diff (7.7 KB) - added by scribu 4 years ago.
Set @since MU. More warnings on switch_to_blog()
14953-3.diff (26.3 KB) - added by SergeyBiryukov 3 years ago.
14953-4.diff (25.5 KB) - added by SergeyBiryukov 3 years ago.

Download all attachments as: .zip

Change History (46)

comment:1 hakre4 years ago

Any patch in sight? September is closing ...

comment:2 scribu4 years ago

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

comment:3 scribu4 years ago

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

comment:5 andrea_r4 years ago

  • Cc andrea_r added

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

comment:6 nacin4 years ago

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
}

comment:7 filosofo4 years ago

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

comment:8 boonebgorges4 years ago

  • Cc boonebgorges added

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

comment:9 boonebgorges4 years ago

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

boonebgorges4 years ago

scribu4 years ago

comment:10 scribu4 years ago

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

comment:11 scribu4 years ago

For @since, I just used 3.0.0

comment:12 nacin4 years ago

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

simonwheatley4 years ago

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

simonwheatley4 years ago

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?

comment:13 follow-up: hakre4 years ago

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.

comment:14 hakre4 years ago

Related: #14953

comment:15 hakre4 years ago

Related: #14783

comment:16 in reply to: ↑ 13 ; follow-up: nacin4 years ago

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.

comment:17 follow-ups: boonebgorges4 years ago

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

boonebgorges4 years ago

comment:18 jacobsantos4 years ago

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.

comment:19 in reply to: ↑ 17 ; follow-up: scribu4 years ago

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

scribu4 years ago

Set @since MU. More warnings on switch_to_blog()

comment:20 scribu4 years ago

  • Keywords has-patch added; needs-patch removed

See ms-blogs.2.diff

comment:21 in reply to: ↑ 19 ; follow-up: scribu4 years ago

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.

comment:22 in reply to: ↑ 21 jacobsantos4 years ago

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.

comment:23 scribu4 years ago

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.

comment:24 scribu4 years ago

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

comment:25 in reply to: ↑ 16 hakre4 years ago

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.

comment:26 scribu3 years ago

To clarify, * @since MU is fine.

comment:27 scribu3 years ago

  • Keywords needs-patch added; has-patch removed

comment:28 scribu3 years ago

  • Type changed from defect (bug) to enhancement

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

comment:29 jane3 years ago

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

comment:30 jane3 years ago

  • Keywords 3.2-early added
  • Milestone changed from 3.1 to Future Release

Beta. Punting. Marking 3.2-early.

comment:31 in reply to: ↑ 17 westi3 years ago

  • Keywords has-patch added; needs-patch removed

Replying to boonebgorges:

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

Looks like this never got committed.

comment:32 westi3 years ago

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

SergeyBiryukov3 years ago

comment:33 SergeyBiryukov3 years ago

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?

comment:34 nacin3 years ago

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

SergeyBiryukov3 years ago

comment:35 SergeyBiryukov3 years ago

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

comment:36 SergeyBiryukov3 years ago

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

comment:37 scribu3 years ago

  • Keywords commit added; 3.2-early removed
  • Milestone changed from Future Release to 3.1

Patch looks good.

comment:38 nacin3 years ago

  • Resolution set to fixed
  • Status changed from new to closed

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

Note: See TracTickets for help on using tickets.