Can we document this in terms of what happens from a user perspective instead of what APIs are called? Just like its done on Android above.

Also: I thought apple doesn't allow popping the root ViewController (see old documentation). What has changed?

Can we document this in terms of what happens from a user perspective instead of what APIs are called? Just like its done on Android above.

The reason I talked about the actual implementation is because "animated" doesn't have a definite meaning. It means whatever Apple decides it means, and could potentially change it. You might even be able to customize it. So, if we said "animated means you will do a slide out animation to the left" that might not be true always. I could say something like "performs UIViewController's dismiss animation", you like that?

Also: I thought apple doesn't allow popping the root ViewController (see old documentation). What has changed?

Yep, that changed. See: https://github.com/flutter/engine/blob/c12b917e95074aec4700dd5554563bc84f93ecc2/shell/platform/darwin/ios/framework/Source/FlutterPlatformPlugin.mm#L197

It now has slightly different semantics for iOS since the platforms' concepts don't really match.

My comment wasn't talking about the documentation about "animated". That one is fine. It was talking about the "popViewControllerAnimated". That one should say in prose what calling "pop" means on iOS, e.g. the FlutterViewController is removed or whatever it does. Similarly to how the Android part documents this.

The link you provided basically has a comment that describes what happens in words instead of in terms of API.

Sorry, github isn't good at displaying chains of PR's. That text was already approved in a previous PR, that's why I as confused.

That one should say in prose what calling "pop" means on iOS

I believe that it is already explained on the first line in prose, "Removes the topmost Flutter instance, presenting what was before it.".

I've added the iOS section about implementation details in order to provide more color. The comment in the code I link referred to "navigation controllers" which is a less specific way to say UINavigationController. I think in this case when we are providing further details; we are doing users a disservice by avoiding concrete classes and methods. I'm happy to chat in person if you want to look into it more =)

nit: Enclose animated in ` instead of [.

Done