#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 follow-up: 2 Changed 11 years ago by
Component: | unfiled → manipulation |
---|---|
Keywords: | needsdocs added |
Priority: | undecided → low |
Status: | new → open |
comment:2 Changed 11 years ago by
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 11 years ago by
Keywords: | needsdocs removed |
---|---|
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.
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.