log: add package documentation and summary of package's purpose

thaJeztah · thaJeztah · commit 6baff1694fe7 · 2023-07-30T22:55:37.000+02:00
Add a package doc to (try to) describe the purpose of this package, and
to describe the purpose (and expectations) of aliases provided by the
package.

&gt; Package log provides types and functions related to logging, passing
&gt; loggers through a context, and attaching context to the logger.
&gt;
&gt; # Transitional types
&gt;
&gt; This package contains various types that are aliases for types in [logrus].
&gt; These aliases are intended for transitioning away from hard-coding logrus
&gt; as logging implementation. Consumers of this package are encouraged to use
&gt; the type-aliases from this package instead of directly using their logrus
&gt; equivalent.
&gt;
&gt; The intent is to replace these aliases with locally defined types and
&gt; interfaces once all consumers are no longer directly importing logrus
&gt; types.
&gt;
&gt; IMPORTANT: due to the transitional purpose of this package, it is not
&gt; guaranteed for the full logrus API to be provided in the future. As
&gt; outlined, these aliases are provided as a step to transition away from
&gt; a specific implementation which, as a result, exposes the full logrus API.
&gt; While no decisions have been made on the ultimate design and interface
&gt; provided by this package, we do not expect carrying "less common" features.

Signed-off-by: Sebastiaan van Stijn &lt;github@gone.nl&gt;
diff --git a/log/context.go b/log/context.go
@@ -14,6 +14,27 @@
    limitations under the License.
 */
 
+// Package log provides types and functions related to logging, passing
+// loggers through a context, and attaching context to the logger.
+//
+// # Transitional types
+//
+// This package contains various types that are aliases for types in [logrus].
+// These aliases are intended for transitioning away from hard-coding logrus
+// as logging implementation. Consumers of this package are encouraged to use
+// the type-aliases from this package instead of directly using their logrus
+// equivalent.
+//
+// The intent is to replace these aliases with locally defined types and
+// interfaces once all consumers are no longer directly importing logrus
+// types.
+//
+// IMPORTANT: due to the transitional purpose of this package, it is not
+// guaranteed for the full logrus API to be provided in the future. As
+// outlined, these aliases are provided as a step to transition away from
+// a specific implementation which, as a result, exposes the full logrus API.
+// While no decisions have been made on the ultimate design and interface
+// provided by this package, we do not expect carrying "less common" features.
 package log
 
 import (
