Bug Tracker

Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#10930 closed bug (fixed)

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.

Change History (3)

comment:1 Changed 6 years ago by dmethvin

Component: unfiledmanipulation
Keywords: needsdocs added
Priority: undecidedlow
Status: newopen

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.

comment:2 in reply to:  1 Changed 6 years ago by 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. :)

comment:3 Changed 6 years ago by addyosmani

Keywords: needsdocs removed
Resolution: fixed
Status: openclosed

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.

Note: See TracTickets for help on using tickets.