Bug Tracker

#10930 closed bug (fixed)

Opened December 01, 2011 01:30AM UTC

Closed February 01, 2012 12:23PM UTC

Last modified March 09, 2012 07:06PM UTC

Documentation bug: Change "internals" category name.

Reported by: anonymous Owned by:
Priority: low Milestone: None
Component: manipulation Version: 1.7.1
Keywords: Cc:
Blocked by: Blocking:
Description

(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.

Attachments (0)
Change History (3)

Changed December 01, 2011 01:38AM UTC by dmethvin comment:1

component: unfiled → manipulation
keywords: → needsdocs
priority: undecided → low
status: new → open

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.

Changed December 01, 2011 01:44AM UTC by anonymous comment:2

Replying to [comment:1 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. :)

Changed February 01, 2012 12:23PM UTC by addyosmani comment:3

keywords: needsdocs
resolution: → fixed
status: open → closed

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.