"ContentDefinition.PopulateSettings" inconsistent documentation

[sarahelsaig]

Describe the bug

The documentation comment of ContentDefinition.Settings says

Do not access this property directly. Migrate to use GetSettings and PopulateSettings.

But PopulateSettings has been removed in #14572. This makes the property documentation confusing, and also makes migration to 1.9.0 harder. I see that in the PR usages of the method have been expanded into direct access of ContentDefinition.Settings.

Discussion

Based on the above linked change in #14572, is the "Do not access this property directly." instruction no longer applicable?
Also, is it safe to access the settings like partFieldDefinition.Settings.ToObject<BooleanFieldSettings>() instead of of partFieldDefinition.GetSettings<BooleanFieldSettings>()?

Suggestion

To avoid confusion, I think we should:

• Update the linked documentation comment.
• Restore PopulateSettings, even just as a stub method that has [Obsolete] and throws NotSupportedException to aid migration.
• Mention the removal of PopulateSettings in 1.9.0.md.
• Replace definition.Settings.ToObject<T>() with definition.GetSettings<T>()?

If you have no objections, I will do the above and submit a PR in the coming days.

[Piedone]

@MikeAlhayek could you chime in here, please?

[MikeAlhayek]

I don't know the real reason why JT removed that extension.

Since 1.9 contains multiple breaking changes around the STJ conversion, I think it is okay to remove the extension method "unless we want to bring it back permanently without the use of Obsolete attribute". But, I also leaning toward not brining it back.

At the very least, the suggested documentation change should be part of the 1.9 breaking changes bullets in the STJ section as well. And the following line should be fixed accordingly

Do not access this property directly. Migrate to use GetSettings and PopulateSettings.