Ticket #7661: 7661.r8954.2.diff

File 7661.r8954.2.diff, 11.1 KB (added by jacobsantos, 4 years ago)

Complete inline documentation for widget.php based off of r8954

  • widgets.php

     
    3535$wp_registered_widgets = array(); 
    3636 
    3737/** 
     38 * Stores the registered widget control (options). 
    3839 * 
    3940 * @global array $wp_registered_widget_controls 
    4041 * @since 2.2.0 
    … …  
    170171} 
    171172 
    172173/** 
    173  * {@internal Missing Short Description}} 
     174 * Register widget for sidebar with backwards compatibility. 
    174175 * 
    175  * {@internal Missing Long Description}} 
     176 * Allows $name to be an array that accepts either three elements to grab the 
     177 * first element and the third for the name or just uses the first element of 
     178 * the array for the name. 
    176179 * 
     180 * Passes to {@link wp_register_sidebar_widget()} after argument list and 
     181 * backwards compatibility is complete. 
     182 * 
    177183 * @since 2.2.0 
    178184 * @uses wp_register_sidebar_widget() Passes the compiled arguments. 
    179185 * 
    180  * @param string $name  
    181  * @param callback $output_callback 
    182  * @param string $classname 
     186 * @param string|int $name Widget ID. 
     187 * @param callback $output_callback Run when widget is called. 
     188 * @param string $classname Classname widget option. 
     189 * @param mixed $params,... Widget parameters. 
    183190 */ 
    184191function register_sidebar_widget($name, $output_callback, $classname = '') { 
    185192        // Compat 
    … …  
    203210} 
    204211 
    205212/** 
    206  * {@internal Missing Short Description}} 
     213 * Register widget for use in sidebars. 
    207214 * 
    208  * {@internal Missing Long Description}} 
     215 * The default widget option is 'classname' that can be override. 
    209216 * 
     217 * The function can also be used to unregister widgets when $output_callback 
     218 * parameter is an empty string. 
     219 * 
    210220 * @since 2.2.0 
    211221 * 
    212  * @uses $wp_registered_widgets {@internal Missing Description}} 
    213  * @uses $wp_register_widget_defaults {@internal Missing Description}} 
     222 * @uses $wp_registered_widgets Uses stored registered widgets. 
     223 * @uses $wp_register_widget_defaults Retrieves widget defaults. 
    214224 * 
    215  * @param int $id {@internal Missing Description}} 
    216  * @param string $name {@internal Missing Description}} 
    217  * @param callback $output_callback {@internal Missing Description}} 
    218  * @param array|string $options {@internal Missing Description}} 
    219  * @return null Will return if $output_callback is empty 
     225 * @param int|string $id Widget ID. 
     226 * @param string $name Widget display title. 
     227 * @param callback $output_callback Run when widget is called. 
     228 * @param array|string Optional. $options Widget Options. 
     229 * @param mixed $params,... Widget parameters to add to widget. 
     230 * @return null Will return if $output_callback is empty after removing widget. 
    220231 */ 
    221232function wp_register_sidebar_widget($id, $name, $output_callback, $options = array()) { 
    222233        global $wp_registered_widgets; 
    … …  
    243254} 
    244255 
    245256/** 
    246  * {@internal Missing Short Description}} 
     257 * Retrieve description for widget. 
    247258 * 
    248  * {@internal Missing Long Description}} 
     259 * When registering widgets, the options can also include 'description' that 
     260 * describes the widget for display on the widget administration panel or 
     261 * in the theme. 
    249262 * 
    250263 * @since 2.5.0 
    251264 * 
    252  * @param unknown_type $id 
    253  * @return unknown 
     265 * @param int|string $id Widget ID. 
     266 * @return string Widget description, if available. Null on failure to retrieve description. 
    254267 */ 
    255268function wp_widget_description( $id ) { 
    256269        if ( !is_scalar($id) ) 
    … …  
    269282 * 
    270283 * @since 2.2.0 
    271284 * 
    272  * @param int $id Same as wp_unregister_sidebar_widget() 
     285 * @param int|string $id Widget ID. 
    273286 */ 
    274287function unregister_sidebar_widget($id) { 
    275288        return wp_unregister_sidebar_widget($id); 
    276289} 
    277290 
    278291/** 
    279  * {@internal Missing Short Description}} 
     292 * Remove widget from sidebar. 
    280293 * 
    281  * {@internal Missing Long Description}} 
    282  * 
    283294 * @since 2.2.0 
    284295 * 
    285  * @param int $id {@internal Missing Description}} 
     296 * @param int|string $id Widget ID. 
    286297 */ 
    287298function wp_unregister_sidebar_widget($id) { 
    288299        wp_register_sidebar_widget($id, '', ''); 
    … …  
    290301} 
    291302 
    292303/** 
    293  * {@internal Missing Short Description}} 
     304 * Registers widget control callback for customizing options. 
    294305 * 
    295  * {@internal Missing Long Description}} 
     306 * Allows $name to be an array that accepts either three elements to grab the 
     307 * first element and the third for the name or just uses the first element of 
     308 * the array for the name. 
    296309 * 
     310 * Passes to {@link wp_register_widget_control()} after the argument list has 
     311 * been compiled. 
     312 * 
    297313 * @since 2.2.0 
    298314 * 
    299  * @param unknown_type $name {@internal Missing Description}} 
    300  * @param unknown_type $control_callback {@internal Missing Description}} 
    301  * @param unknown_type $width {@internal Missing Description}} 
    302  * @param unknown_type $height {@internal Missing Description}} 
     315 * @param int|string $name Sidebar ID. 
     316 * @param callback $control_callback Widget control callback to display and process form. 
     317 * @param int $width Widget width. 
     318 * @param int $height Widget height. 
    303319 */ 
    304320function register_widget_control($name, $control_callback, $width = '', $height = '') { 
    305321        // Compat 
    … …  
    324340        call_user_func_array('wp_register_widget_control', $args); 
    325341} 
    326342 
    327 /* $options: height, width, id_base 
    328  *   height: never used 
    329  *   width:  width of fully expanded control form.  Try hard to use the default width. 
    330  *   id_base: for multi-widgets (widgets which allow multiple instances such as the text widget), an id_base must be provided. 
    331  *            the widget id will ennd up looking like {$id_base}-{$unique_number} 
    332  */ 
    333343/** 
    334  * {@internal Missing Short Description}} 
     344 * Registers widget control callback for customizing options. 
    335345 * 
    336  * {@internal Missing Long Description}} 
     346 * The options contains the 'height', 'width', and 'id_base' keys. The 'height' 
     347 * option is never used. The 'width' option is the width of the fully expanded 
     348 * control form, but try hard to use the default width. The 'id_base' is for 
     349 * multi-widgets (widgets which allow multiple instances such as the text 
     350 * widget), an id_base must be provided. The widget id will end up looking like 
     351 * {$id_base}-{$unique_number}. 
    337352 * 
    338353 * @since 2.2.0 
    339354 * 
    340  * @param int $id {@internal Missing Description}} 
    341  * @param string $name {@internal Missing Description}} 
    342  * @param callback $control_callback {@internal Missing Description}} 
    343  * @param array|string $options {@internal Missing Description}} 
     355 * @param int|string $id Sidebar ID. 
     356 * @param string $name Sidebar display name. 
     357 * @param callback $control_callback Run when sidebar is displayed. 
     358 * @param array|string $options Optional. Widget options. See above long description. 
     359 * @param mixed $params,... Optional. Additional parameters to add to widget. 
    344360 */ 
    345361function wp_register_widget_control($id, $name, $control_callback, $options = array()) { 
    346362        global $wp_registered_widget_controls; 
    … …  
    377393 * @since 2.2.0 
    378394 * @see wp_unregister_widget_control() 
    379395 * 
    380  * @param int $id Widget ID. 
     396 * @param int|string $id Widget ID. 
    381397 */ 
    382398function unregister_widget_control($id) { 
    383399        return wp_unregister_widget_control($id); 
    384400} 
    385401 
    386402/** 
    387  * {@internal Missing Short Description}} 
     403 * Remove control callback for widget. 
    388404 * 
    389  * {@internal Missing Long Description}} 
    390  * 
    391405 * @since 2.2.0 
    392  * @uses wp_register_widget_control() {@internal Missing Description}} 
     406 * @uses wp_register_widget_control() Unregisters by using empty callback. 
    393407 * 
    394  * @param int $id {@internal Missing Description}} 
     408 * @param int|string $id Widget ID. 
    395409 */ 
    396410function wp_unregister_widget_control($id) { 
    397411        return wp_register_widget_control($id, '', ''); 
    398412} 
    399413 
    400414/** 
    401  * {@internal Missing Short Description}} 
     415 * Display dynamic sidebar. 
    402416 * 
    403  * {@internal Missing Long Description}} 
     417 * By default it displays the default sidebar or 'sidebar-1'. The 'sidebar-1' is 
     418 * not named by the theme, the actual name is '1', but 'sidebar-' is added to 
     419 * the registered sidebars for the name. If you named your sidebar 'after-post', 
     420 * then the parameter $index will still be 'after-post', but the lookup will be 
     421 * for 'sidebar-after-post'. 
    404422 * 
     423 * It is confusing for the $index parameter, but just know that it should just 
     424 * work. When you register the sidebar in the theme, you will use the same name 
     425 * for this function or "Pay no heed to the man behind the curtain." Just accept 
     426 * it as an oddity of WordPress sidebar register and display. 
     427 * 
    405428 * @since 2.2.0 
    406429 * 
    407  * @param unknown_type $index 
    408  * @return unknown 
     430 * @param int|string $index Optional, default is 1. Name or ID of dynamic sidebar. 
     431 * @return bool True, if widget sidebar was found and called. False if not found or not called. 
    409432 */ 
    410433function dynamic_sidebar($index = 1) { 
    411434        global $wp_registered_sidebars, $wp_registered_widgets; 
    … …  
    461484} 
    462485 
    463486/** 
    464  * {@internal Missing Short Description}} 
     487 * Whether widget is registered using callback with widget ID. 
    465488 * 
    466  * {@internal Missing Long Description}} 
     489 * Will only check if both parameters are used. Used to find which sidebar the 
     490 * widget is located in, but requires that both the callback and the widget ID 
     491 * be known. 
    467492 * 
    468493 * @since 2.2.0 
    469494 * 
    470  * @param unknown_type $callback 
    471 /* @return mixed false if widget is not active or id of sidebar in which the widget is active 
     495 * @param callback $callback Widget callback to check. 
     496 * @param int $widget_id Optional, but needed for checking. Widget ID. 
     497/* @return mixed false if widget is not active or id of sidebar in which the widget is active. 
    472498 */ 
    473499function is_active_widget($callback, $widget_id = false) { 
    474500        global $wp_registered_widgets; 
    … …  
    486512} 
    487513 
    488514/** 
    489  * {@internal Missing Short Description}} 
     515 * Whether the dynamic sidebar is enabled and used by theme. 
    490516 * 
    491  * {@internal Missing Long Description}} 
    492  * 
    493517 * @since 2.2.0 
    494518 * 
    495  * @return unknown 
     519 * @return bool True, if using widgets. False, if not using widgets. 
    496520 */ 
    497521function is_dynamic_sidebar() { 
    498522        global $wp_registered_widgets, $wp_registered_sidebars; 
    … …  
    510534/* Internal Functions */ 
    511535 
    512536/** 
    513  * {@internal Missing Short Description}} 
     537 * Retrieve full list of sidebars and their widgets. 
    514538 * 
    515  * {@internal Missing Long Description}} 
     539 * Will upgrade sidebar widget list, if needed. Will also save updated list, if 
     540 * needed. 
    516541 * 
    517542 * @since 2.2.0 
    518543 * @access private 
    519544 * 
    520  * @param unknown_type $update 
    521  * @return unknown 
     545 * @param bool $update Optional, default is true. Whether to save upgrade of widget array list. 
     546 * @return array Upgraded list of widgets to version 2 array format. 
    522547 */ 
    523548function wp_get_sidebars_widgets($update = true) { 
    524549        global $wp_registered_widgets, $wp_registered_sidebars; 
    … …  
    599624} 
    600625 
    601626/** 
    602  * {@internal Missing Short Description}} 
     627 * Set the sidebar widget option to update sidebars. 
    603628 * 
    604  * {@internal Missing Long Description}} 
    605  * 
    606629 * @since 2.2.0 
    607630 * @access private 
    608  * @uses update_option()  
    609631 * 
    610  * @param unknown_type $sidebars_widgets 
     632 * @param array $sidebars_widgets Sidebar widgets and their settings. 
    611633 */ 
    612634function wp_set_sidebars_widgets( $sidebars_widgets ) { 
    613635        update_option( 'sidebars_widgets', $sidebars_widgets ); 
    614636} 
    615637 
    616638/** 
    617  * {@internal Missing Short Description}} 
     639 * Retrieve default registered sidebars list. 
    618640 * 
    619  * {@internal Missing Long Description}} 
    620  * 
    621641 * @since 2.2.0 
    622642 * @access private 
    623643 * 
    624  * @return unknown 
     644 * @return array 
    625645 */ 
    626646function wp_get_widget_defaults() { 
    627647        global $wp_registered_sidebars;