There's been some offline conversation (mostly between Bob and myself) about math library namespaces and I wanted to bring the conversation out to the broader community for comments. The problem we're noticing is that as it currently stands, the math library has a large surface area and there are many components that are public that are more like implementation details, that we would like to 1) be able to change without downstream warning and 2) put less effort into documenting. Things that fit into this category include a lot of the metaprogramming stuff in the math library, things like VectorView (or really most stuff in /meta/).
The C++ language doesn't have an amazing solution to this, and it seems like most people in the community just designate certain namespaces as non-public, called something like
internal (we actually have both of these in our code already).
That said, Bob pointed out that we might have several different math library user profiles, and there's an open question about how to categorize these and how closely to model our internal namespaces after how we think our users are categorized. One could imagine a strict hierarchy, where some users always want more of the internals than others, or you could imagine functional slices of the library relevant to different users, etc. For example, some users just want to describe and fit models using the existing functionality and some users might want to create their own distributions and even algorithms.
What do you all think is a good split? My gut instinct (being pretty new and not knowing any external users of the math library) would be to treat everything used in the Stan language as public and everything else as
detail, I have no preference on the name).