Add reference documentation for secret()

[Gijsreyn]

PR Summary

This pull request adds the reference documentation for the secret() function. Also, minor tweaks were made to the CLI command function to accommodate the addition of more functions without breaking the documentation.

PR Context

[Gijsreyn]

@michaeltlombardi After revisiting the examples, I have removed examples 3 and 4. Additionally, examples 1 and 2 have been rewritten, as they cannot be used in a string concatenation (still wondering why it couldn't be done even though the ARM docs also always directly use it on a property).

[michaeltlombardi]

I'm not sure how to address this, but if you can currently use the Echo resource to emit secrets retrieved with the secret() function, that's probably something we need to fix.

I'm not sure exactly how to manage this problem yet - but if all you need to do to dump secrets from someone's vault is guess the name and invoke a config, that's not good.

CC @SteveL-MSFT

[SteveL-MSFT]

If you can access the secret (meaning authenticated in some way), you already have access to the secret in memory (or other means). Resources need the secret itself in plaintext and we can only prevent accidental exposure of it, we aren't a security boundary to prevent access to something that have to use.

If we want to add a layer of defense, we could say that secrets are always passed as JSON:

{ "secureString": "plaintext" }

But now anything that needs it needs to parse the JSON and would also need to handle it appropriately anyways, so I'm not sure it adds value since the recipient would already know it's a sensitive string.