The flag-handling logic added in #4421 may change semantics, so this commit adds a warning to the documentation for this feature.