From 7842e757ff8f9d8fc067fcc29c371d1d425f4501 Mon Sep 17 00:00:00 2001 From: John Bintz Date: Thu, 19 Nov 2009 07:27:10 -0500 Subject: [PATCH] add documentation to functions.inc --- functions.inc | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/functions.inc b/functions.inc index 56be18d..ff9dcb3 100644 --- a/functions.inc +++ b/functions.inc @@ -7,8 +7,12 @@ foreach (array( 'Unprotect' => 0, 'R' => 3, 'RT' => 3, + 'RL' => 2, + 'In_R' => 2, 'M' => 1, - 'EM' => 3 + 'EM' => 3, + 'SL' => 1, + 'SC' => 2, ) as $function => $param_count) { if ($param_count == 0) { add_action("comicpress-${function}", $function, 10); @@ -32,6 +36,7 @@ function F($name, $path, $override_post = null) { /** * Protect global $post and $wp_query. + * @param object $use_this_post If provided, after saving the current post, set up this post for template tag use. */ function Protect($use_this_post = null) { global $post, $wp_query, $__post, $__wp_query; @@ -67,6 +72,13 @@ function Unprotect() { $__post = $__wp_query = null; } +/** + * Prepare the restrictions for R functions. + * This does some pre-processing before the R functions send the restrictions off to get_${which}_post. + * @param array $restrictions The restrictions to use to find categories. + * @param object $override_post The post to use for restrictions that reference a post automatically. + * @return array The list of restrictions to use. + */ function __prep_R($restrictions, $post_to_use) { if (is_string($restrictions)) { switch ($restrictions) { @@ -105,6 +117,13 @@ function __prep_R($restrictions, $post_to_use) { // @codeCoverageIgnoreStart +/** + * Find a post relative to the provided post. + * @param string $which The relative direction to search. Choices: first, last, next, previous + * @param array $restrictions The restrictions to use to find categories. + * @param object $override_post The post to check. If not provided, use the Loop post saved by Protect(). + * @return object|false The found post, or false if not found. + */ function R($which, $restrictions = null, $override_post = null) { global $post; $post_to_use = !is_null($override_post) ? $override_post : $post; @@ -125,6 +144,13 @@ function R($which, $restrictions = null, $override_post = null) { return $new_post; } +/** + * Find a post relative to the provided post and, if found, force the Loop to use this post for template tags. + * @param string $which The relative direction to search. Choices: first, last, next, previous + * @param array $restrictions The restrictions to use to find categories. + * @param object $override_post The post to check. If not provided, use the Loop post saved by Protect(). + * @return object|false The found post that is now being used for template tags, or false if not found. + */ function RT($which, $restrictions = null, $override_post = null) { global $post, $__post; if (!empty($override_post)) { @@ -143,6 +169,12 @@ function RT($which, $restrictions = null, $override_post = null) { // @codeCoverageIgnoreEnd +/** + * Get the list of categories that match the provided restrictions. + * @param array $restrictions The restrictions to use to find categories. + * @param object $override_post The post to check. If not provided, use the current Loop post. + * @return array The list of categories that match the provided restrictions. + */ function RL($restrictions = null, $override_post = null) { global $post; $post_to_use = !is_null($override_post) ? $override_post : $post; @@ -154,6 +186,12 @@ function RL($restrictions = null, $override_post = null) { return $storyline->build_from_restrictions($restrictions); } +/** + * Check if the provided post is in any of the categories matched by the restrictions. + * @param array $restrictions The restrictions to use to find categories. + * @param object $override_post The post to check. If not provided, use the current Loop post. + * @return boolean True if the post is in the list of categories matched by the restrictions. + */ function In_R($restrictions = null, $override_post = null) { global $post; $post_to_use = !is_null($override_post) ? $override_post : $post; @@ -171,6 +209,11 @@ function In_R($restrictions = null, $override_post = null) { return false; } +/** + * Retrieve post attachment info to be used with EM(). + * @param object $override_post The post to retrieve attachment info for. If not provided, use the current Loop post. + * @return array The list of attachment info. + */ function M($override_post = null) { global $post, $__attachments; $post_to_use = !is_null($override_post) ? $override_post : $post; @@ -181,6 +224,13 @@ function M($override_post = null) { return $__attachments; } +/** + * Call a function on the backend specified by the provided attachment info. + * @param array $attachment_info The post attachment info from M(). + * @param string $which The subattachment short name to reference. + * @param string $action The method to call on the backend. + * @return object The result from the backend. + */ function EM($attachment_info, $which = 'default', $action = 'embed') { if (substr($action, 0, 1) != '_') { $args = func_get_args(); @@ -199,12 +249,25 @@ function EM($attachment_info, $which = 'default', $action = 'embed') { } } +/** + * Return the raw storyline structure. + * @return array The astoryline structure from ComicPressStoryline + */ function SL() { $storyline = new ComicPressStoryline(); $storyline->read_from_options(); return $storyline->_structure; } +/** + * Get a category relative to the provided category. + * If no category is provided, use the current post's category. + * Relative measures can be one of: current, previous, lext, level, parent + * If no relative measure is provided, the current category is returned. + * @param string $which The relative measure to use. + * @param object $relative_to The post object to be relative to. + * @return object|false The relative category object, or false if not found. + */ function SC($which = 'current', $relative_to = null) { global $post;