# Contributing to ®ina;

This page serves as a checklist for adding new code to ®ina;.

- ®ina; is written in &cpp;, and so any permanent contributions to ®ina; will need to be written in &cpp; also.

- New classes should use value semantics, unless there is a good reason not to. Classes with value semantics should provide appropriate comparisions (`==` and `!=`), copy constructors, and copy assignment operators. If they are large objects, they should also provide move constructors, move assignment operators, a member `swap()` function, and a global `swap()` function.

- New code should ideally come with corresponding tests for ®ina;'s test suite:

  - For important classes, these tests should be comprehensive, not just a few token cases. See the `Integer` tests in `testsuite/maths/integer.cpp` for an example of very comprehensive testing.
  - The tests may be either &cpp; (in `testsuite/`) or &python; (in `python/testsuite/`), or both. &python; tests are simpler to write; however, the &cpp; tests can be far more flexible in what is tested (not just comparing text output), and moreover the &cpp; tests will be run on more systems (including those where &python; development files are not available).
  - Whilst they should be comprehensive, tests should not be enormously slow. Watch how fast/slow the other tests are as a guide for what is acceptable (if you test using “`make test ARGS=-V`” then you can see each individual test as it runs).

- All functions and classes should be fully documented. In particular, for each function:

  - The first sentence of the documentation should be appropriate to display as a brief synopsis (since this will be extracted and placed into various indices).
  - The documentation should list all preconditions that the user needs to ensure before calling the function.
  - Functions should not be correct only for “common” scenarios, but should be as general as possible within reason. Any limitations should be made clear to the user (e.g., through explicit preconditions)—users should not be expected to guess which scenarios the function works for.
  - All parameters should be described in individual `\param` blocks. Likewise, any non-type template parameters (e.g., integer template parameters) must be described in `\tparam` blocks. Of course, type parameters may be described also if this will be helpful. The return value should be described in a `\return` block.
  - All preconditions that the user is expected to adhere to should be spelled out in the documentation. Limits on function arguments (e.g., acceptable integer ranges) can be listed in each `\param` block; other preconditions should be listed in separate `\pre` paragraphs.
  - If there are differences between the &cpp; and &python; versions of a function or class, these should be listed in a separate `\python` paragraph. In particular, if function arguments differ (e.g., the &cpp; version takes a pair of iterators but the &python; version takes a single list), then the arguments should be named in the &python; bindings using `pybind11::arg(...)`. If there is no &python; version at all, this should be made clear using a `\nopython` tag (which can take an optional explanation).

- Documentation needs to be written in a format that is easy for humans to read in the &cpp; headers, will be formatted appropriately when processed by &doxygen;, and will convert sensibly to a &python; docstring. Best practices include:

  - Avoid &html; tags such as `<i>`, `<b>`, and `<tt>` where possible—instead use markdown and/or &doxygen; tags. In particular: for italicised English, use `_underscores_`; for italicised variable names use `\a`; for bold English use `**double asterisks**`; for &cpp; keywords use `\c`; and for inline code fragments use ``backticks``. Note that &doxygen; does not (currently) translate underscores within `\exception` blocks; here you will need to italicise using `\e` (for single words) or `<i>` (for multiple words).
  - Avoid &xml; entities such as `&lt;`, `&amp;`, and `&ne;`. For less-than, you can use `\<` if there is a risk of &doxygen; misinterpreting a plain `<` as an &html; tag. For mathematical symbols with “simple” unicode representations (i.e., likely to be supported in fonts across many platforms), just use the unicode instead. Simple unicode symbols include: `≤≥≠`, `×±`, `αβπ`, and `¹²³`.
  - Use &doxygen;-style backslash tags such as `\param`, not Javadoc-style tags such as `@param`.

- All &cpp; functions and classes should have corresponding &python; bindings, unless there is a very good reason not to. The &python; bindings are typically easy to write, and Ben can help with this if necessary.

  - Template classes should be wrapped in &python; using suffixes that describe the template arguments. See for example `Triangulation3`, or `TreeEnumeration_NonSpun`.
  - All functions and classes wrapped in &python; should have appropriate docstrings, which need to be passed to the corresponding `pybind11::def(...)` statement. These docstrings are extracted automatically from the hand-written documentation in the &cpp; headers, and this extraction is done manually (not as part of the build process). Please ask Ben if you need this extraction to be run for you.
  - If for some reason you are binding a function in &python; but you do not want to extract a docstring (this should be a rare occurrence), use a `\nodocstring` tag in the &cpp; class or function documentation. (At the time of writing, `\nodocstring` is used in only two places across ®ina;'s entire &api;.)