Contributing New Functions to Stan (dev guide page)

Developers
3

I’ll add a few things here too since I’ve been going through this.

From a high level, I like the Math docs. The Stan docs are a bit more confusing though. I’ve only done simple things like adding linkage for new functions, but it’s not clear to me what things I should be testing in Stan itself (as opposed to Math). I haven’t really ever had to look at the interface codes to make my stuff work (which is nice!).

Broadly speaking, the Contributing New Functions to Stan page is excellent

I agree totally. Stan + Stan-math are largely a very pleasant pieces of software to work with. There are some issues on this page (Contributing New Functions to Stan · stan-dev/stan Wiki · GitHub) though:

  1. The directions in Directories for code make sense to me now that I know what everything is, but I think it needs more words explaining what things are (what is prim? what is rev? what is mix?) stan::math::rev should be stan::math::var? A link to the built Nomad manual would be useful with respect to mix.
  2. src/test/gm/model_specs/compiled/ doesn’t seem to exist (presumably this was in Stan?)
  3. src/test/unit-agrad-rev/functions/ doesn’t exist (presumably this was in Math?)
  4. make test-unit doesn’t work on the Math library or the Stan library
  5. test/gm doesn’t exist (is this src/test/gm from Stan?)
  6. The Model Tests blurb seems really important, but I had a lot of trouble parsing it (still not sure I understand it – there seem to be a lot of tests there for Math functions, but a lot of Math function tests also seem to be missing [or I could be missing them])
  7. Everything in Creating a C++ Function for Stan down is useful, but it feels like a second version of the stuff I just read (I like the 2nd version better, honestly).

The second is that some of the @throw doxygen comments are a bit odd

Agreed. It’s annoying to burrow through the error checks and find out exactly what error is being thrown (and could lead to outdated docs if that underlying error changes)

For the unit testing, I don’t have the foggiest what the TEST( arg, arg)

I agree. Maybe some Stan-specific info on how the Google unit test stuff is used could be useful. It’s been annoying enough to me that I don’t want to go anywhere near it (EXPECT_THROW/EXPECT_NO_THROW consuming errors). Maybe I should just RTFM, but it’s too many layers removed from the fun stuff for me to really want to stress myself out over it.