Improve doc comments in promauto

In particular, point out that `With(nil)` is valid.

Signed-off-by: beorn7 <beorn@grafana.com>
This commit is contained in:
beorn7 2020-06-03 13:56:49 +02:00
parent 056e8af303
commit 3ba240a80f
1 changed files with 26 additions and 24 deletions

View File

@ -127,29 +127,30 @@
// separate package? // separate package?
// //
// The main problem is that registration may fail, e.g. if a metric inconsistent // The main problem is that registration may fail, e.g. if a metric inconsistent
// with the newly to be registered one is already registered. Therefore, the // with or equal to the newly to be registered one is already registered.
// Register method in the prometheus.Registerer interface returns an error, and // Therefore, the Register method in the prometheus.Registerer interface returns
// the same is the case for the top-level prometheus.Register function that // an error, and the same is the case for the top-level prometheus.Register
// registers with the global registry. The prometheus package also provides // function that registers with the global registry. The prometheus package also
// MustRegister versions for both. They panic if the registration fails, and // provides MustRegister versions for both. They panic if the registration
// they clearly call this out by using the Must… idiom. Panicking is a bit // fails, and they clearly call this out by using the Must… idiom. Panicking is
// problematic here because it doesn't just happen on input provided by the // problematic in this case because it doesn't just happen on input provided by
// caller that is invalid on its own. Things are a bit more subtle here: Metric // the caller that is invalid on its own. Things are a bit more subtle here:
// creation and registration tend to be spread widely over the codebase. It can // Metric creation and registration tend to be spread widely over the
// easily happen that an incompatible metric is added to an unrelated part of // codebase. It can easily happen that an incompatible metric is added to an
// the code, and suddenly code that used to work perfectly fine starts to panic // unrelated part of the code, and suddenly code that used to work perfectly
// (provided that the registration of the newly added metric happens before the // fine starts to panic (provided that the registration of the newly added
// registration of the previously existing metric). This may come as an even // metric happens before the registration of the previously existing
// bigger surprise with the global registry, where simply importing another // metric). This may come as an even bigger surprise with the global registry,
// package can trigger a panic (if the newly imported package registers metrics // where simply importing another package can trigger a panic (if the newly
// in its init function). At least, in the prometheus package, creation of // imported package registers metrics in its init function). At least, in the
// metrics and other collectors is separate from registration. You first create // prometheus package, creation of metrics and other collectors is separate from
// the metric, and then you decide explicitly if you want to register it with a // registration. You first create the metric, and then you decide explicitly if
// local or the global registry, and if you want to handle the error or risk a // you want to register it with a local or the global registry, and if you want
// panic. With the constructors in the promauto package, registration is // to handle the error or risk a panic. With the constructors in the promauto
// automatic, and if it fails, it will always panic. Furthermore, the // package, registration is automatic, and if it fails, it will always
// constructors will often be called in the var section of a file, which means // panic. Furthermore, the constructors will often be called in the var section
// that panicking will happen as a side effect of merely importing a package. // of a file, which means that panicking will happen as a side effect of merely
// importing a package.
// //
// A separate package allows conservative users to entirely ignore it. And // A separate package allows conservative users to entirely ignore it. And
// whoever wants to use it, will do so explicitly, with an opportunity to read // whoever wants to use it, will do so explicitly, with an opportunity to read
@ -252,7 +253,8 @@ type Factory struct {
} }
// With creates a Factory using the provided Registerer for registration of the // With creates a Factory using the provided Registerer for registration of the
// created Collectors. // created Collectors. If the provided Registerer is nil, the returned Factory
// creates Collectors that are not registered with any Registerer.
func With(r prometheus.Registerer) Factory { return Factory{r} } func With(r prometheus.Registerer) Factory { return Factory{r} }
// NewCounter works like the function of the same name in the prometheus package // NewCounter works like the function of the same name in the prometheus package