Various possible Docs enhancements

[a-teammate]

As discussed in slack I shortly write down my review suggestions reading the docs.
Already mentioned: the reason I write this is, that for me as novice user (without any dnd background) It was a bit missing the implicit knowledge domain experts have here.

• be proud of the fact that HTML5 dnd is not used! clearly mark why this is not done and the advantages this lib brings with it, thanks to this implementation detail. (see the elm-pointer-events docs which link an interesting article complaining about html5 dnd)

• "auxiliary items" -> keep it simple: "helper items"

  • also they should not be mentioned everywhere. It is not a nice addition that they are required, it is a "bug"/restriction. So that should be clearly marked. ("The nature of drag and drop implementations like ours, which is based on dropzone, requires that either at the end or at the beginning an additional item must be placed, serving as a placeholder. Otherwise it would not be possible to place..")

• the doc is separate from the code.. imo that makes it a bit hard to read in the sense that its "hard to inspect the actual type definitions" and the actual code when reading the doc.

• the doc examples are not self-contained

  • in the beginning section there is always a recipe of user-code copied from the example. But that requires deep understanding of the previous code of the example.
    • instead it could be done as follows: crisp explanation of the function, showing an example input+output, explaining the reasons why the function is required, then showing where to put it into user code
  • the doc uses a "read it all or die" approach, instead of a lookup on need.
  • Imo it would be much more helpful if e.g. the fields of a type are inline commented. And also if the sections of the initial doc would directly be put next to the code. no need in copying the example imo, otherwise people can read the DndList.Group example instead.

• "update"

  • "and the sorted list in the model": it is user responsibility where to keep the list. they should put it in the model, but thats an additional hint given after the explanation. Suggestion: "..and the resorted list of items. These should be saved back to your model and used for the next call to DndList.update."

• dragEvents

  • the example is missing the explanation what the example does.
    • e.g: the dragevents are only attached when there is no dragging going on! same for the dropevents are only attached when there is a dragging going on. 1) why? 2) explain!
  • there is no shorthand description of what "dragEvents" is:
    • given the html of a node and the index in the flat list across all groups, it returns for that item the list of events HTML Attributes, making that item dragable.

• dropEvents

  • why is there a footer needed? please explain! (and when)
    • "a footer is needed, so you can drag items to the end of the group. Imagine it like an invisible placeholder to serve as the target zone, to allow a drop at the end of a list when the operation would be "add the item before the item hovered on drop". Similarily a header placeholder is needed for "insertAfter" operations. Also it is required for empty lists."• example for adding a custom ghoststlye does not work
  • currentPosition should be used.

• why is the main example adding new sections like "---- SYSTEM ---- "?

  • Might just be bc I am such an elm-newbie, though. But for me it was hard to sectionize this afterwards, bc i was unsure whether i also need to add this new section now. Also I didnt see the term "system" before used in elm.
  • Maybe also this could be renamed to "dndSystem" throughout the docs, to signal that this is a special thing for the library.
  • My feeling is, that this System concept can maybe be simplified with a different API, but I also do not have a better idea. I mean the purpose of having the user create the system, instead of hiding it behind the curtains of the module is adding complexity. I know the reason is to allow independent dnd lists, where items can not be transferred betwen those lists. Maybe take inspiration of the style ir4y/elm-dnd does it? (Although that one is limited in functionality, maybe more code for lists could actually be emulated with specially provided dragMeta-dropMeta records and some separate helper tools?)

• config: explain when the provided operations (comparator, setter) are executed. For me this was only clear after reading the source code. and only after realizing that placeholder items are needed for the groups, to give the guarantees for those functors.Other