sszuev commented on PR #1994: URL: https://github.com/apache/jena/pull/1994#issuecomment-1696990958
> IMO the javadoc should focus on the API contract. If it hints at more, a few application writers will chance it! > > For iterators, testing or seeing modifications work isn't enough to guarantee the code. Different amounts of data change whether a modification inside the processing loop succeeds or crashes. Blank nodes mean two runs on the same data files may behave differently. > > Implementations can change - but code writing to the contract will work. > > When the material gets into discussion, for example when it says "may", that feels more like advice which is more suited for a [How To](https://jena.apache.org/documentation/notes/index.html) on the subject. The javadoc can link to the material. > > The contract is: > > * run to exhaustion or close the iterator > > * use `finally` to be sure > > * No modification inside the processing loop of the iterator > > * `ExtendedIterator.remove` is not guaranteed and for general code, should not be relied upon. Agree. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
