== You can't use _expvar.Func_ to expose a bunch of expvar types

Suppose, hypothetically, that you have a collection of statistics
that are each one of [[the _expvar_ package
https://golang.org/pkg/expvar/]]'s types. You want to put them in
a namespace (so they are all '_mything.var1_', '_mything.var2_' and
so on), but you'd like to avoid the [[tedious clutter GoExpvarNotes]]
of registering each expvar variable by hand with _.Set()_. So you
have a clever idea.

First, you will embed all of the variables in a structure:

.pn prewrap on

>  var somestats struct {
>     var1, var2, var3   expvar.Int
>     var4, var5, var6   expvar.Int
>  }

Then you will write a _Stats()_ function that simply hands back
the structure and then register it through _expvar.Func()_:

>  func ReportStats() interface{} {
>     return somestats
>  }

Unfortunately, this will not work (at least today). As I mentioned
in [[my first set of notes on the expvar package GoExpvarNotes]],
_expvar.Func_ turns what your function returns into JSON by using
[[json.Marshal https://golang.org/pkg/encoding/json/#Marshal]], and
this only returns *exported fields*. None of the expvar variable
types have any exported fields, and so as a result _expvar.Func()_
will convert them all to empty JSON (or possibly malfunction).
You just can't get there from here.

This is kind of a bug (at a minimum, _expvar.Func_ should document
this restriction), but it's unlikely to change (apart from the
documentation being updated). Beyond it not working today, there's
no way to have a simple _ReportStats_ function like this that work
safely, and since you can't do this there's little to no point in
making expvar variable types JSON-serializable through json.Marshal.

(To make this work, each expvar type would implement a _MarshalJSON()_
method that did the appropriate thing. In fact, since _expvar.String_
is really MarshalJSON() in disguise, you could just make one call the
other.)

=== Sidebar: Why clear and complete documentation matters

Here is a question: is it deliberate that the 'thing to JSON'
function for _expvar.Var_ is not called _MarshalJSON_, or is it a
historical accident? You can certainly argue that because my pattern
above is fundamentally wrong, it's a feature that it doesn't work
at all. Thus the choice of not using _MarshalJSON_ in the _expvar.Var_
interface could be entirely deliberate and informed, since it makes
a broken thing (and all its variants) simply not work.
Or this could be ultimately a mistake on the order of [[using
_String()_ in the _expvar.Var_ interface GoExpvarVarGotcha]], and
so something that would be corrected in a hypothetical Go 2 (which
is allowed to change APIs).

Without better documentation, people who come along to Go later
just don't know. If you want to preserve the intent of the original
designers of the language and the standard library, it really helps
to be clear on what that intent *is* and perhaps the logic behind
it. Otherwise it's hard to tell deliberate decisions from accidents.