Changeset 7452 for trunk/bp-core/bp-core-template-loader.php

Timestamp:

10/22/2013 01:55:08 AM (12 years ago)

Author:

boonebgorges

Message:

Improve inline docs in bp-core. See #5022

File:

• trunk/bp-core/bp-core-template-loader.php (modified) (18 diffs)

trunk/bp-core/bp-core-template-loader.php

@@ -2 +2 @@
 
 /**
- * BuddyPress Template Functions
+ * BuddyPress Template Functions.
  *
  * This file contains functions necessary to mirror the WordPress core template
@@ -16 +16 @@
 
 /**
- * Adds BuddyPress theme support to any active WordPress theme
- *
- * @since BuddyPress (1.7)
- *
- * @param string $slug
- * @param string $name Optional. Default null
+ * Get a BuddyPress template part for display in a theme.
+ *
+ * @since BuddyPress (1.7.0)
+ *
  * @uses bp_locate_template()
  * @uses load_template()
  * @uses get_template_part()
+ *
+ * @param string $slug Template part slug. Used to generate filenames, eg
+ *        'friends' for 'friends.php'.
+ * @param string $name Optional. Template part name. Used to generate
+ *        secondary filenames, eg 'personal' for 'activity-personal.php'.
+ * @return string Path to located template. See {@link bp_locate_template()}.
  */
 function bp_get_template_part( $slug, $name = null ) {
@@ -51 +55 @@
  * not found in either of those, it looks in the theme-compat folder last.
  *
- * @since BuddyPress (1.7)
+ * @since BuddyPress (1.7.0)
  *
  * @param string|array $template_names Template file(s) to search for, in order.
- * @param bool $load If true the template file will be loaded if it is found.
- * @param bool $require_once Whether to require_once or require. Default true.
- *                            Has no effect if $load is false.
+ * @param bool $load Optional. If true, the template file will be loaded when
+ *        found. If false, the path will be returned. Default: false.
+ * @param bool $require_once Optional. Whether to require_once or require. Has
+ *        no effect if $load is false. Default: true.
  * @return string The template filename if one is located.
  */
@@ -98 +103 @@
 
 /**
- * This is really cool. This function registers a new template stack location,
- * using WordPress's built in filters API.
+ * Register a new template stack location.
  *
  * This allows for templates to live in places beyond just the parent/child
@@ -105 +109 @@
  * with bp_locate_template(), this allows for easy template overrides.
  *
- * @since BuddyPress (1.7)
- *
- * @param string $location Callback function that returns the stack location
- * @param int $priority
+ * @since BuddyPress (1.7.0)
+ *
+ * @todo Make 'callable' instead of 'function'.
+ *
+ * @param string $location Callback function that returns the stack location.
+ * @param int $priority Optional. The priority parameter as passed to
+ *        add_filter(). Default: 10.
+ * @return bool See {@link add_filter()}.
  */
 function bp_register_template_stack( $location_callback = '', $priority = 10 ) {
@@ -121 +129 @@
 
 /**
- * Deregisters a previously registered template stack location.
- *
- * @since BuddyPress (1.7)
- *
- * @param string $location Callback function that returns the stack location
- * @param int $priority
+ * Deregister a previously registered template stack location.
+ *
+ * @since BuddyPress (1.7.0)
+ *
  * @see bp_register_template_stack()
+ *
+ * @param string $location Callback function that returns the stack location.
+ * @param int $priority Optional. The priority parameter passed to
+ *        {@link bp_register_template_stack()}. Default: 10.
+ * @return bool See {@link remove_filter()}.
  */
 function bp_deregister_template_stack( $location_callback = '', $priority = 10 ) {
@@ -140 +151 @@
 
 /**
- * Call the functions added to the 'bp_template_stack' filter hook, and return
+ * Get the "template stack", a list of registered directories where templates can be found.
+ *
+ * Calls the functions added to the 'bp_template_stack' filter hook, and return
  * an array of the template locations.
  *
  * @see bp_register_template_stack()
  *
- * @since BuddyPress (1.7)
- *
- * @global array $wp_filter Stores all of the filters
- * @global array $merged_filters Merges the filter hooks using this function.
- * @global array $wp_current_filter stores the list of current filters with the current one last
- *
+ * @since BuddyPress (1.7.0)
+ *
+ * @global array $wp_filter Stores all of the filters.
+ * @global array $merged_filters Merges the filter hooks using this function..
+ * @global array $wp_current_filter stores the list of current filters with
+ *         the current one last.
  * @return array The filtered value after all hooked functions are applied to it.
  */
@@ -192 +205 @@
 
 /**
- * Get a template part in an output buffer, and return it
- *
- * @since BuddyPress (1.7)
- *
- * @param string $slug
- * @param string $name
- * @return string
+ * Put a template part into an output buffer, and return it.
+ *
+ * @since BuddyPress (1.7.0)
+ *
+ * @see bp_get_template_part() for a description of $slug and $name params.
+ *
+ * @param string $slug See {@link bp_get_template_part()}.
+ * @param string $name See {@link bp_get_template_part()}.
+ * @param bool $echo If true, template content will be echoed. If false,
+ *        returned. Default: true.
+ * @return string|null If $echo, returns the template content.
  */
 function bp_buffer_template_part( $slug, $name = null, $echo = true ) {
@@ -223 +240 @@
 
 /**
- * Retrieve path to a template
+ * Retrieve the path to a template.
  *
  * Used to quickly retrieve the path of a template without including the file
@@ -230 +247 @@
  * locations without the use of the other get_*_template() functions.
  *
- * @since BuddyPress (1.7)
- *
- * @param string $type Filename without extension.
- * @param array $templates An optional list of template candidates
+ * @since BuddyPress (1.7.0)
+ *
  * @uses bp_set_theme_compat_templates()
  * @uses bp_locate_template()
  * @uses bp_set_theme_compat_template()
+ *
+ * @param string $type Filename without extension.
+ * @param array $templates An optional list of template candidates.
  * @return string Full path to file.
  */
@@ -272 +290 @@
 
 /**
- * Add template locations to template files being searched for
- *
- * @since BuddyPress (1.7)
- *
- * @param array $stacks
- * @return array()
+ * Add template locations to template files being searched for.
+ *
+ * @since BuddyPress (1.7.0)
+ *
+ * @param array $stacks Array of template locations.
+ * @return array() Array of all template locations registered so far.
  */
 function bp_add_template_stack_locations( $stacks = array() ) {
@@ -294 +312 @@
 
 /**
- * Add checks for BuddyPress conditions to parse_query action
- *
- * @since BuddyPress (1.7)
+ * Add checks for BuddyPress conditions to 'parse_query' action.
+ *
+ * @since BuddyPress (1.7.0)
  *
  * @param WP_Query $posts_query
@@ -319 +337 @@
 
 /**
- * Possibly intercept the template being loaded
+ * Possibly intercept the template being loaded.
  *
  * Listens to the 'template_include' filter and waits for any BuddyPress specific
@@ -328 +346 @@
  * from being stomped on accident.
  *
- * @since BuddyPress (1.7)
+ * @since BuddyPress (1.7.0)
  *
  * @param string $template
- *
- * @return string The path to the template file that is being used
+ * @return string The path to the template file that is being used.
  */
 function bp_template_include_theme_supports( $template = '' ) {
@@ -349 +366 @@
 
 /**
- * Set the included template
- *
- * @since BuddyPress (1.8)
- * @param mixed $template Default false
- * @return mixed False if empty. Template name if template included
+ * Set the included template.
+ *
+ * @since BuddyPress (1.8.0)
+ *
+ * @param mixed $template Default: false.
+ * @return mixed False if empty. Template name if template included.
  */
 function bp_set_template_included( $template = false ) {
@@ -364 +382 @@
  * Is a BuddyPress template being included?
  *
- * @since BuddyPress (1.8)
- * @return bool True if yes, false if no
+ * @since BuddyPress (1.8.0)
+ * @return bool True if yes, false if no.
  */
 function bp_is_template_included() {
@@ -372 +390 @@
 
 /**
- * Attempt to load a custom BuddyPress functions file, similar to each themes
- * functions.php file.
- *
- * @since BuddyPress (1.7)
+ * Attempt to load a custom BP functions file, similar to each themes functions.php file.
+ *
+ * @since BuddyPress (1.7.0)
  *
  * @global string $pagenow
@@ -399 +416 @@
 
 /**
- * Get the templates to use as the endpoint for BuddyPress template parts
- *
- * @since BuddyPress (1.7)
- *
- * @uses apply_filters()
- * @return array Of possible root level wrapper template files
+ * Get the templates to use as the endpoint for BuddyPress template parts.
+ *
+ * @since BuddyPress (1.7.0)
+ *
+ * @return array Array of possible root level wrapper template files.
  */
 function bp_get_theme_compat_templates() {