[wp-trac] [WordPress Trac] #14953: Add inline documentation to MultiSite functions

[WordPress Trac]

#14953: Add inline documentation to MultiSite functions
--------------------------+-------------------------------------------------
 Reporter:  scribu        |       Owner:             
     Type:  defect (bug)  |      Status:  new        
 Priority:  normal        |   Milestone:  3.1        
Component:  Inline Docs   |     Version:  3.0        
 Severity:  normal        |    Keywords:  needs-patch
--------------------------+-------------------------------------------------

Comment(by nacin):

 Replying to [comment:13 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.

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/14953#comment:16>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software