[wp-trac] [WordPress Trac] #25381: Hook Docs: wp-signup.php

[WordPress Trac]

#25381: Hook Docs: wp-signup.php
-------------------------+------------------------------
 Reporter:  miyauchi     |       Owner:
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  Inline Docs  |     Version:
 Severity:  normal       |  Resolution:
 Keywords:  has-patch    |
-------------------------+------------------------------

Comment (by DrewAPicture):

 Hi miyauchi,

 [attachment:wp-signup.2.diff] is a good start.

 General notes:
 * Change "Fires actions" to "Fires"
 * `@since` versions should use the 3-digit x.x.x style, e.g. 3.0.0
 * Short descriptions should all start with a capital letter
 * All `@param` lines need a short description ending with a period
 * Try to avoid "Allows" in filter descriptions. Focus on '''what''' is
 filterable. e.g. "Filter X"
 * Space out all documented action or filter lines (only) per coding
 standards. e.g.
 `do_action('signup_blogform', $errors);`
 becomes
 `do_action( 'signup_blogform', $errors );`
 * Generally: clarity over succinctness is preferred. Short descriptions
 should be a complete sentence

 Specific hooks:
 * Remove `// allow definition of default variables` since it's being
 replaced
 * For the `signup_another_blog_init` filter, the `@param` is incorrect.
 I'd suggest breaking the array out to a variable first, then using the
 variable in the filter. For instance:
 {{{
 #!php
 <?php
 $signup_defaults = array(
         'blogname'   => $blogname,
         'blog_title' => $blog_title,
         'errors'     => $errors
 );
 /**
  * Filter default site signup variables.
  *
  * @since 3.0.0
  * @param array $signup_defaults An array of default site signup
 variables.
  */
 $filtered_results = apply_filters( 'signup_another_blog_init',
 $signup_defaults );
 }}}
 * Some short descriptions need to be more clear. Such as "Add extra hidden
 fields to the form of sign up another blog." could be clearer as "Add
 extra hidden fields to the site signup form.
 * The `signup_create_blog_meta` filter needs the same treatment as the
 `signup_another_blog_init` filter example above
 * "Filter for the new" should be "Filter the new"

 I'm gonna stop here. Let's work through the stuff I talked about above to
 the point you can generate a new patch then we'll see where we're at :)

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