They're also not really at the same level of decision no? The pageRouteBuilder is fed into the _onGenerateRoute when building individual routes. The builder is outside the route and outside the navigator altogether.

As implemented, pageRouteBuilder will get ignored if builder is specified - that may be wrong, but it's how it is. Maybe it's be more appropriate to say the routing implementation needs to know how to appropriately build a new widget when routing?

Sounds unexpected. Perhaps you're referring to https://github.com/flutter/flutter/blob/master/packages/flutter/lib/src/widgets/app.dart#L646? (in that case we should probably rename the similarly named local variable).

I also meant we should clarify what the choice the user is to make (which are at different scales of 'complexity'). If you override pageRouteBuilder, given the page content builder that the user already provided, decorate it with a route. If you override builder, you're building everything. That difference in scale should be described.

Ahh you are absolutely right. I'll update the doc and rename the local there.

maybe it should be pageContentBuilder or something

Overriding builder doens't really mean overriding everything though - builder gets passed a child, it's meant to just be a wrapper around whatever we'd be doing normally.