is_single() or its documentation needs update

[sirzooro]

I have compared how is_single() works with its documentation, and I am a bit confused:

• implementation: is_single() returns true for Posts, Attachments and Custom Post Types; for Pages it returns false;
  
• documentation on ​codex: "When any single Post page is being displayed." (my understanding: it should return true for Posts only);
  
• inline documentation in code: "Whether the current page query is single page. [...] This applies to other post types, attachments, pages, posts. Just means that the current query has only a single object.".

Need to determine how this function should really works, and update it, its inline doc and/or codex accordingly.

[nacin]

The inline docs are wrong. is_single is not true for pages.

is_singular is true for posts, pages, custom post types, attachments.

[mrmist]

I've updated the referenced Codex doc to reflect that is_single returns true for attachement and custom types, but not for Pages.

[sirzooro]

OK, but current function behavior is correct or not? Codex doc for this function is in "A Single Post Page" section, so I would expect that this function should be used to detect if we are on Post page or not. I have searched Internet for it, and found that others write something similar about it.

What's more, in WP2.9 and earlier we need to use more complex condition to detect if current page is Post or not - something like this:
if ( is_single() && !is_attachment() )
In 3.0 we can use is_singular( 'page' ) to do this, but this is not backward-compatible.

Therefore I am not sure if this is correct. I would like to get extra feedback from other people about this.

[nacin]

IIRC: is_single() should return true for posts only. is_singular() returns true for pages, posts, and attachments.

Let's fix the docs.

[PeteMall]

is_single() currently returns true for custom post types which is a bug.

[nacin]

We might need to accept that as new functionality.

[nacin]

Technically, is_singular = is_single || is_page || is_attachment, but when is_attachment is true, is_single xor is_page is also true.

is_single() cannot be counted on for attachments due to a specific case where is_attachment = is_page = true, but for the most part, is_single() checks any post type other than pages.

Let's have the docs reflect this. is_singular() checks any post type. is_page() checks pages. is_attachment() checks attachments. is_single() checks posts, any other post type, and usually returns true for attachments.

[scribu]

(In [16830]) Clarify is_single() inline doc. Fixes #14034