Deprecate --templates-dir option.

[kallentu]

Related to #3480.

Deprecate the option. (Which I'm actually not sure what more there is to do besides writing it in the command help. Let me know.)
Added an entry to the changelog for this change.

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[srawlins]

In documentation_comment.dart, you can see how we warn( if the examplePathPrefix value is non-null. The same can be done in templates.dart, when templatesDir is non-null.

[kallentu]

In documentation_comment.dart, you can see how we warn( if the examplePathPrefix value is non-null. The same can be done in templates.dart, when templatesDir is non-null.

Oh, happy to do that!
I looked around for a bit and couldn't find a Warnable that I could "warn" on. I think at that point in templates.dart, we haven't even built the package graph. Hmm, am I missing something?

[srawlins]

Ah good catch. No I can't find anything easy to hang the warning on there. But the RuntimeTemplates there is used in a GeneratorBackend, so we could just delay the warning until it is used by the GeneratorFrontEnd (*grumble* inconsistent camel casing 😠), and trigger it based on is RuntimeTemplates, which is a little hacky.

A good spot might be at the beginning of GeneratorFrontEnd._generateDocs, something like if ((_generatorBackend as GeneratorBackendBase).templates is RuntimeTemplates) { packageGraph.defaultPackage.warn(...); }.

I don't like that cast, so maybe GeneratorFrontEnd._generatorBackend can be made a GeneratorBackendBase, or maybe one of the types in the hierarchy can be removed. A spoonful of tech debt helps the simple feature deprecation go down. 😁

[kallentu]

Added the warning for this, PTAL again :)