[wp-trac] [WordPress Trac] #44224: Missing @return in Doc comment

[WordPress Trac]

#44224: Missing @return in Doc comment
-------------------------------------------------+-------------------------
 Reporter:  subrataemfluence                     |       Owner:
                                                 |  subrataemfluence
     Type:  defect (bug)                         |      Status:  assigned
 Priority:  normal                               |   Milestone:  5.1
Component:  Plugins                              |     Version:  trunk
 Severity:  normal                               |  Resolution:
 Keywords:  has-patch good-first-bug needs-      |     Focuses:  docs
  refresh                                        |
-------------------------------------------------+-------------------------

Comment (by subrataemfluence):

 @desrosj, None of `$plugin_page` and `$parent_page arguments` has a
 default value set.

 Now since `get_admin_page_parent` function argument has a default value
 (empty string) set for `$parent`, I think adding a default value (empty
 string) for `$parent_page` might worth. By doing this we can keep this
 argument optional.

 As far as `$plugin_page` argument is concerned, it has no default value
 set, so to my understanding, `Required` should be used for this. In other
 words, again, to me understanding, argument doesn't have a default value
 specified should probably be declared as `Required`.

 I would suggest the following modification in Doc block and argument list:

 {{{#!php
 <?php
 /**
  *
  * @global array $admin_page_hooks
  * @param string $plugin_page. Name of the page generated by plugin.
 Required.
  * @param string $parent_page. Name of the parent page of $plugin_page.
  */

 function get_plugin_page_hookname( $plugin_page, $parent_page = '' ) {
    ...
    $parent = get_admin_page_parent( $parent_page );
    ...
 }
 }}}


 Please let me know if it makes sense!

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/44224#comment:12>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform