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.