[WIP] Add comments/docstrings to exceptions

[craddm]

✅ Checklist

• You have given your pull request a meaningful title (e.g. Enable foobar integration rather than 515 foobar).
• You are targeting the appropriate branch. If you're not certain which one this is, it should be develop.
• Your branch is up-to-date with the target branch (it probably was when you started, but it may have changed since then).
• You have marked this pull request as a draft and added '[WIP]' to the title if needed (if you're not yet ready to merge).

⤴️ Summary

Adds descriptive comments and/or docstrings to exceptions.

Also checks consistency of usage across the codebase.

🌂 Related issues

Closes #1518

🔬 Tests

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
data_safe_haven/commands
shm.py					108
sre.py					179
data_safe_haven/exceptions
__init__.py
Project Total

This report was generated by python-coverage-comment-action

[craddm]

Currently the custom exceptions use the following hierarchy:

[craddm]

I'm still trying to understand what we want the errors to achieve. At the moment they're a bit of a mishmash.

For example, DataSafeHavenParameterError is used when a user supplies a key for a context that either does not exist or already exists (when trying to create), but also when a yaml config file cannot be validated.

On the other hand, we have DataSafeHavenConfigError, which is used when no context file exists, or when a user supplies an SRE name that does not exist in the config, but also when no context is selected, or when the config file is not correct yaml.

Then we have DataSafeHavenInputError which is used when a subscription cannot be found, when there are missing values for users, when a secret already exists in a key-vault...

Finding it difficult to nail a description for some of these error classes as it's not always clear what they are intended to capture

[jemrobinson]

It's totally fine for you to redesign the error names and/or inheritance structure to make more sense. I think we want things to adhere to the following guidelines:

• everything should inherit from DataSafeHavenError eventually
• if X and Y both inherit from A it should be because they're conceptually both a type of A but that it's worth distinguishing between them (e.g. it might be nice to distinguish Azure errors from Graph errors even though they're both some kind of Microsoft/Cloud error).
• we (ideally) should be using each type of error in more than one place and, if possible, more than one file

Anything else you'd add to this @JimMadge ?