The stuff in the detail namespace isn’t part of the Math library’s public API, not even for people who might be writing distributions. There was a discussion at some point that lead to us deciding that we can safely hide implementation details in there without full doxygen doc.
In my hazy memory, I think I remember a discussion, but I don’t remember a decision taking place. Whatever we do, can we document it somewhere? Preferably in a wiki: https://github.com/stan-dev/math/wiki
A few points:
- I’m not in favor of complete lack of documentation. It encourages bad behavior (and I’ve been guilty of this too). I’m looking at this in terms of future maintenance. It’s really hard to follow code when there’s not really context. And I’ve seen on this project, future contributors often take functions and apply them or adjust them to address yet another use case and this can cause major problems. Having some doc as to purpose helps.
- I’m in favor of testing these functions, even though there is no expectation that it would be called directly by a client to the math library. Even having a test that demonstrates how to call the function is useful for debugging in the future. If it’s code that’s at the heart of everything, I think that’s the least that we should require. Not having that makes it difficult for anyone else coming in to help debug. This comes from first-hand experience where I’ve spent lots and lots and lots of hours on code (some mine) where there wasn’t even a single test to show how to call a function and most of the time is spent figuring out how to instantiate it correctly. After that, it’s easier.
Anyway, I’m ok with the
stan::math::detail namespace something that we treat as not officially part of the API. We should just put that down somewhere.