chore(metrics): expose MetricsInterface as return type of single metric and further improve API docs

[dreamorosi]

Summary

Changes

Please provide a summary of what's being changed

This PR started out with the goal of modifying the return type of the Metrics.singleMetric() method to use MetricsInterface instead of Metrics. This small change allows for easier customization of the utility and avoids a cyclical type reference.

While working on this, I realized that the MetricsInterface was out of date and had no documentation whatsoever, which means its API page is empty and there's no contextual documentation in the IDE when customers hover any of the interface or properties.

At that point the goal shifted towards making sure the methods and their API docs in the Metrics class and the MetricsInterface were aligned. In doing so, I also noticed that some of the public methods were somewhat under documented and at least in some cases, there were opportunities to either clarify the purpose of the method or add a code snippet.

This ended becoming a seizable PR that further improved on the work started by @am29d in a previous PR and complemented the API docs added in that PR by expanding some of the descriptions and introducing a bunch of links between methods/sections.

For example, now the API docs for the addMetric() method goes in detail on how to use the method but also links to other relevant parts of the API docs:

This work was enabled by @am29d's work on fixing our TypeDoc setup and making sure links are properly rendered & followed. I have applied this type of pattern across the entire Metrics package and also made sure all code samples and wording is consistent across API docs & README.

Finally, while there, I noticed that we had a public method named throwOnEmptyMetrics() which was severely under documented and that didn't do what I'd have expected it to do. I marked it as deprecated in favor of a newly added method setThrowOnEmtpymetrics(enabled: boolean) which is clearer on its purpose and is also aligned with other similar public setter methods in terms of naming.

Please add the issue number below, if no issue is present the PR might get blocked and not be reviewed

Issue number: closes #3132

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[dreamorosi]

The 2 accepted issues marked by SonarCloud are related to the deprecated method still being used in the unit tests. For now I marked them as such since these tests will be refactored soon when moving the utility to Vitest, and the method will eventually be removed in the next major version.

[leandrodamascena]

Hey @dreamorosi! I just have 2 small comments.

I saw you're changing code in Metrics.ts and types/Metrics.ts and for me looks good. If the tests are green, good to merge.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
2 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud