#3702 First|Next|Done docs are confusing

[Don Porter]

The Tcl_DictObj(First|Next|Done) routines
are offered to manage an iteration through
the contents of a dictionary.

The documentation says:

"The donePtr argument points to a variable that is
updated to be zero of there are further key/value
pairs to be iterated over, or non-zero if the
iteration is complete."

I interpret that to mean a result of (*donePtr = 1)
means the next call to Tcl_DictObjNext would fail
to return anything, so it need not be made.

That's not what the implementation does.

The implementation has (*donePtr = 1) means that
the current call did not return anything.

Either scheme is workable, but the docs need
to be more clear. Confusion about whether/when
Tcl_DictObjDone() needs to be called caused
Tcl Bug 1710709.

[Donal K. Fellows]

Logged In: YES
user_id=79902
Originator: NO

Originally, Done was only called when you wanted to break out of iterating early, and this was found to work well enough in the basic implementations in tclDictObj.c. But later on (when I was writing the bytecode compiled versions IIRC) I discovered that this in fact sucked and was too hard to use right, and that it was better instead to arrange for Done to be always callable after the iteration completed. (I believe that the Done call can be avoided in the same circumstances that it always could be avoided, but it's easier to avoid having to explain it by making repeat calls idempotent.)

I do not recall at what point I wrote the documentation. :-)