wp_trim_excerpt does not trim text if you pass text in.

[aubreypwd]

/**
 * Generates an excerpt from the content, if needed.
 *
 * The excerpt word amount will be 55 words and if the amount is greater than
 * that, then the string ' […]' will be appended to the excerpt. If the string
 * is less than 55 words, then the content will be returned as is.
 *
 * The 55 word limit can be modified by plugins/themes using the {@see 'excerpt_length'} filter
 * The ' […]' string can be modified by plugins/themes using the {@see 'excerpt_more'} filter
 *
 * @since 1.5.0
 *
 * @param string $text Optional. The excerpt. If set to empty, an excerpt is generated.
 * @return string The excerpt.
 */
function wp_trim_excerpt( $text = '' ) {
	$raw_excerpt = $text;
	if ( '' == $text ) {
		$text = get_the_content('');

		$text = strip_shortcodes( $text );

		/** This filter is documented in wp-includes/post-template.php */
		$text = apply_filters( 'the_content', $text );
		$text = str_replace(']]>', ']]>', $text);

		/**
		 * Filters the number of words in an excerpt.
		 *
		 * @since 2.7.0
		 *
		 * @param int $number The number of words. Default 55.
		 */
		$excerpt_length = apply_filters( 'excerpt_length', 55 );
		/**
		 * Filters the string in the "more" link displayed after a trimmed excerpt.
		 *
		 * @since 2.9.0
		 *
		 * @param string $more_string The string shown within the more link.
		 */
		$excerpt_more = apply_filters( 'excerpt_more', ' ' . '[…]' );
		$text = wp_trim_words( $text, $excerpt_length, $excerpt_more );
	}
	/**
	 * Filters the trimmed excerpt string.
	 *
	 * @since 2.8.0
	 *
	 * @param string $text        The trimmed text.
	 * @param string $raw_excerpt The text prior to trimming.
	 */
	return apply_filters( 'wp_trim_excerpt', $text, $raw_excerpt );
}

If I pass in $text it would not get trimmed and stripped. Ideally, the passed in $text should override the $text = get_the_content('');.

[adhun]

Hi aubreypwd,

As per the wordpress codex reference for wp_trim_excerpt it cleary says that

If you supply text it will be returned untouched. It will not be shortened.

[aubreypwd]

This was a little dismissive. I'm not questioning if documentation is wrong or right, I'm saying that the expectation behind this function is misleading and inefficient. I would expect if I passed a function called wp_trim_excerpt some text it would trim what I sent it, or it would always, at least, return a trimmed something. Why pass text to a function that simply returns it back to me? It just makes no sense.

Maybe it should return the generated text (trimmed) and the parameter should be deprecated since it does nothing except filter it.