Resource function documentation bicep examples can be misleading

[afscrome]

Is your feature request related to a problem? Please describe.
https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-resource?tabs=bicep

The template function documentation has several bicep examples. Whilst the examples do correctly document the functiosn in question, there are often better ways to avoid those functions in Bicep.

Describe the solution you'd like

Whilst the non optimal examples are probably still ultimately needed as they're needed to document the function, it would be ideal of the documentation could highlight situations where the functions can be replaced with more idiomatic bicep that better maintain type safety. For example:

• reference() --> resource.foo when the resource was defined in the same module
• reference() --> existing syntax for getting a resource not used in the same module.
  • Or anything else that comes out of Proposal - simplifying resource referencing (part 1) #2245
• *resourceId() --> resource.id

[alex-frankel]

Good suggestion - @tfitzmac @mumian it would be good if we could add this context to docs

[mumian]

@alex-frankel - I will work on this.

[mumian]

https://github.com/MicrosoftDocs/azure-docs-pr/pull/157346

[mumian]

#please-close