How to document correctly?/How to add a new function's documentation to the Stan Function Reference?

Hey guys,

I am working on a new function that I want to add to the stan-math library (see #2682).

My first question is: How do I document correctly?

I already created the index.html from the doxygen.cfg. This creates an entry in the “Stan math library”. Does this suffice for documentation? Or do I also have to create an entry on the “Stan functions Reference”? If so, how do I do this?

My second question is: I somewhere read that the doxygen command should not yield any warnings. In my case, there are plenty of warnings. But none is related to my file. Is it still ok? Can I ignore all those warnings?

Best,
Franzi

1 Like

Hi, @Franzi:

There’s the Doxygen doc within the function itself, which follow standard Doxygen styles.

Then there’s an entry in the Functions Reference. And if it impacts other things perhaps changes to the User’s Guide (for example, when there’s a more efficient way to do something with a new function or a new capability exposed).

The best thing to do is try to take a stab at writing this to look like the other ones. The format for the functions reference is a bit of a hack to get the indexing to work right.

And yes, you can ignore the doxygen errors that aren’t yours. We need to fix those.

2 Likes

Hi @Bob,
thanks! Great, I already created the doxygen text within the function itself.

But where do I edit the Functions Reference and the User’s Guide? I have not found the right place yet.

That’ll be a pull request to stan-dev/docs. You’ll also need to add the function to stan-dev/stanc3. But those can wait until your Stan Math pull request has been accepted.

1 Like

Ah, ok. Thank you very much @nhuurre :)