Documentation of framework role(s) in proto definition is confusing

The documentation for role-related fields in FrameworkInfo is confusing: the role field is marked as deprecated while the roles field is marked as EXPERIMENTAL and has an additional NOTE advising to not use this field.

This leaves users confused what field they should use in their code. Depending on how the proto definition is used deprecated might even produce (fatal) errors, while roles seems strongly discouraged.

We should clean this up to make sure users always know which field they should use.