Documentation bug: Change "internals" category name.

[anonymous]

(Low priority) Documentation bug:

After having a discussion on StackOverflow with a user with respect to the pushStack method, it became apparent that he thought pushStack shouldn't be used because it is part of the "Internals" category, and thereby designated as for internal use only.

I'd suggest either:

• Change the name to something more "inviting", or

• Keep the name, but add a note that they are indeed part of the public API

Or if these are items truly intended for internal use only, either:

• Remove them from the public API documentation, or

• Keep them documented, but add a note stating that they are meant for internal use only.

Obviously a low priority bug, but I do see the confusion it can cause.

[dmethvin]

I can see the confusion, but anything we document is public. Anything we don't document is private. If you're writing a filtering plugin that returns a new set, it should generally use .pushStack() and the docs aren't clear about that.

[anonymous]

Replying to dmethvin:

I can see the confusion, but anything we document is public. Anything we don't document is private.

That was my position as well, but I had to poke around a bit to be sure.

I didn't think you guys would document "internal use only" stuff in the public API, but if it is dissuading people from using some features, it may be worth an update on some slow day. :)

[addyosmani]

The 'internals' category was missing a description so I've added one to say 'Although this category is referred to as ‘internal’, any methods documented within the API site should be considered public and may be freely used.' (a slight variation may appear on there at the moment due to caching). If we feel more needs to be done to make it clearer, we can create a reusable that appears on any posts within the internals category.