Improves documentation around the fields package

See merge request !241



Merged-by: Doug Barrett <dbarrett@gitlab.com>
Approved-by: Doug Barrett <dbarrett@gitlab.com>
Approved-by: Igor <iwiedler@gitlab.com>
Reviewed-by: GitLab Duo <gitlab-duo@gitlab.com>
Co-authored-by: e_forbes <eforbes@gitlab.com>

When working through the gitlab-shell migration, I identified the
need to write log messages to a log file. The code to do this can
be a little clunky, and it's easy to mess up the combination of flags
required to be successful in all cases.

An alternative option explored was to offer a ToFile method, but this
solution didn't provide an elegant way to close the file on application
shutdown. As a result, we've changed direction to go for NewWithFile
that returns the closer. It's a little clunkier, but I'd prefer this
over the potential for incidents.

Whilst digging in further, by default o.sFile will be finalized by the GC
when the application exits according to the SetFinalizer documentation.

https://pkg.go.dev/runtime#SetFinalizer

However, this feels like a recipe for some weird edge cases that will
be forgotten about at some point in the future. As a result, I've
opted to change the API for a slightly more verbose option that
returns the io.Closer which the application can then decide to close
when it's terminating.

feat: Adds a NewWithFile constructor function for specifying log file output

See merge request !264



Merged-by: Igor <iwiedler@gitlab.com>
Approved-by: Igor <iwiedler@gitlab.com>
Reviewed-by: Doug Barrett <dbarrett@gitlab.com>
Reviewed-by: Manuel Schönlaub <mschoenlaub@gitlab.com>
Co-authored-by: e_forbes <eforbes@gitlab.com>