Improve documentation and naming of arguments
JannikGM opened this issue · comments
I tried using FlatQueue but accidentally mixed up id and value parameters.
I was under the impression that id would be some order-index, whereas value would be the actual data associated with that element. However, in reality it's the other way around.
The naming of the id parameter is what led to this confusion.
Before I understood the issue, I even wrote a wrapper because I wanted to pop the data associated with the element (instead of the order-index), because I thought FlatQueue only allowed popping the order-index.
The naming of the peek() / peekValue() functions made my confusion worse.
Even when I understood this, it also wasn't clear to me wether the order-index (value parameter) had to be an integer, or wether it could also be a rational number. It was also unclear wether the order-index could be negative.
And lastly, it also wasn't clear what happens if the same order-index is used multiple times.
It's also not clear how people should check for items in the queue: while(flatqueue.length > 0) or while(flatqueue.peekValue() !== undefined); for API stability, this should probably be documented.
Hopefully it's clearer now after #5 and other docs updates.