IssueTracker

Component used: Navigation

Version used: 2.4.0

Devices/Android versions reproduced on: This is a documentation issue rather than a software issue.

If this is a bug in the library, we would appreciate if you could attach:

• Sample project to trigger the issue.
• A screenrecord or screenshots showing the issue (if UI related).

The documentation for NavOptions.shouldPopUpToSaveState() and NavOptions.Builder.setPopUpTo() both mention that in order to restore state, the restore ID must be "the same ID as popUpToId (note: this matching ID is true whether isPopUpToInclusive is true or false)."

The documentation is a bit confusing and what it says is not always the case. To quote Ian Lake, "what actually happens is that the saved state is associated with a particular ID. The saved state of an ID is restored when you navigate to that ID with restoreState as true. The tricky part is the inclusive flag on popUpTo. Ideally the ID that the saved state is saved under is the ID of the last destination you pop. I.e., if you have A -> B -> C and you popUpTo A with inclusive as false, the state would be saved under the ID of B And while we do always do that (save the state under the ID of the last thing popped), we also need to do one other thing - we save the state under the ID that you passed to popUpTo. This is how you can actually get back to the first saved state"

This part of the documentation should be removed entirely or updated to reflect how things actually work.