Add reference to log_at_level API

[Matthew Hambley (MatthewHambley)]

Description

In order to support a common usage pattern around only calculating debug values if they are actually going to be logged, an addition has been made to the logging API. This change documents that.

Closes #134

Linked issues

The API change is implemented in ticket 4682 of the core repository.

Type of change

• New feature (non-breaking change which adds functionality).
• Breaking change (fix or feature that would cause existing functionality to not work as expected).
• This change requires a documentation update.

How has this been tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration.

• New tests have been added.
• Tests have been modified to accommodate this change.
• GitHub workflows have been changed or added.

Checklist:

• The change has been checked for design compliance by an experienced SSE
  
• My code follows the style guidelines of this project.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes, for both debug and optimised builds.
• No AI tools have been used in the creation of this change.

Reasoning on why any of the above boxes have not been checked

This is a documentation only change.

Review Checks (To be filled in by the reviewer/s)

• Has the developer completed the appropriate sections above?
• Is the change compliant with LFRic Core principles?
• Is the testing coverage sufficient?
• Have any technical debt workarounds identified had issues opened and interested parties notified?

[Steve Mullerworth (stevemullerworth)]

Couple of minor comments.

[Steve Mullerworth (stevemullerworth)]

Suggest removing the "only", as the underlying function does do other hidden work (shutting down the communicator, for example). For the same reason the "This rather..." sentence should be removed as it may imply that it is not necessary to call final_logger (it may not be necessary, but we would like people to do it).

[Matthew Hambley (MatthewHambley)]

Rewritten

[Steve Mullerworth (stevemullerworth)]

It's a good to note the duplication, but I could imagine that a block could include log_level_trace messages and call subroutines that have log_level_info messages.

I wouldn't labour these points though as they are moderately obvious. I'd suggest "Note that it would be normal to duplicate log_level_debug in the final call to log_event".

[Matthew Hambley (MatthewHambley)]

Rewritten. I want to labour it a little to make people stop and think about what they would expect.

[Steve Mullerworth (stevemullerworth)]

All fine now.