#2 Establish a library wide error handling convention

[Thomas Mueller]

dzlib has no consistent error handling pattern: some functions return a Boolean, some raise an exception, some fail silently.

The library already has a convention in places, e.g. GetHdVolumeName / TryGetHdVolumeName in u_dzOsUtils: the Try function returns a Boolean with an out parameter, the other raises. A first worked example: GetModuleFilename in src/u_dzOsUtils.pas returns an empty string when Windows.GetModuleFileName fails, so the caller cannot tell failure from anything else. Adding TryGetModuleFilename and having GetModuleFilename raise EOSError would apply the convention; it changes what every consuming program sees on failure, so it should be done once the guideline is settled.

Also tracked as issue 11 in dzlib's ISSUES.md.

[Thomas Mueller]

Changing what an existing function does on failure is too dangerous: a caller that does not expect an exception would break, and the compiler cannot warn it. So the convention is:

• New functions that can fail come in pairs: TryXxx returns a Boolean with an out parameter, Xxx raises.
• An existing function that fails silently keeps doing so and gets a TryXxx next to it. Its doc comment says what it returns on failure.
• An existing function that already raises stays as it is.
• If an existing function is really wrong, the correct behaviour gets a new name and the old function is marked deprecated.

For the example in the description, this means adding TryGetModuleFilename, while GetModuleFilename keeps returning an empty string instead of raising EOSError.