Draggable documention should say that appendTo is for use with helper

[andrewbadr]

The documention for the appendTo option on draggable doesn't say that it only works if the helper element isn't already in the DOM. The relevant line is:

if(!helper.parents('body').length)
    helper.appendTo((o.appendTo == 'parent' ? this.element[0].parentNode : o.appendTo));

This seems to be meant only for use with the 'clone' option, but there's nothing saying that. It could be confusing.

[Scott González]

Actually, the document is pretty clear that it's for the helper. "The element passed to or selected by the appendTo option will be used as the draggable helper's container during dragging. By default, the helper is appended to the same container as the draggable." How would you word this differently so as to be explicit but not redundant?

[andrewbadr]

What does "helper" mean?

1. The element that is being dragged, regardless of whether it is the original draggable or a cloned element

OR

2. Only the "clone" case

Your changes and comment on this ticket, if I understand them correctly, imply that definition 2 is correct. If so, that's the source of my misunderstanding. But the docs are far from clear, in ways that I can elaborate on.

[Scott González]

#2, but your definition is wrong. Cloning is one of an infinite number of possibilities for a helper. The documentation and default value for helper are confusing, because helper: "original" is really "no helper". This is being addressed in the API redesign in which the default will be helper: null.

Please provide your suggestions for updates to make the documentation more clear.

[andrewbadr]

The terms should be defined somewhere, probably on the overview page.

Besides the 'helper' option documentation that you already mentioned, the main problem is the naming on the callback argument, ui.helper. If no helper is specified, ui.helper refers to the original draggable, strongly suggesting that definition (1) above is correct.

[mikesherov]

Thanks andrewbadr! Im closing this temporarily to eventually move it to the API docs issue tracker.

[Scott González]

Definition (1) above is not correct. The name of the ui property is what's confusing. If you have a suggestion for better wording that doesn't make the assumption that (1) applies to appendTo, please reply to this ticket or send a pull request to modify ​https://github.com/jquery/api.jqueryui.com/blob/master/entries/draggable.xml

Thanks.

[mikesherov]

Thanks scott. I was only adding needsdocs as a temporary thing until I can in one shot port them over. Glad you took care of it.