Add Documentation section to style guide

doc/topics/style-guide.md

@@ -147,6 +147,68 @@ Not covered by C++ Core Guidelines.
 
 * Test files should be prefixed with `Test`, e.g. `TestModel` instead of `ModelTests`.
 
+## ✏️ Documentation
+
+Not covered by C++ Core Guidelines.
+
+Our documentation is generated by Doxygen before being published [online](https://cesium.com/learn/cesium-native/ref-doc). Therefore, any public API should be documented with Doxygen-compatible comments that make use of the following tags (in the listed order):
+
+- `@brief`: Summarize the purpose of the class, function, etc.
+- `@remarks`: Use for any side comments, e.g., how invalid inputs or special cases are handled.
+- `@warning`: Convey any warnings about the use of the class, function, etc., e.g., invalid values that make it unsafe.
+- `@tparam`: Describe template parameters.
+- `@param`: Denote and describe function parameters.
+- `@returns`: Describe the return value of a non-`void` function.
+- `@throws`: Describe any exceptions that a function throws.
+
+Additionally, make sure to:
+
+- Put comments **above** the thing being documented (instead of inline).
+- Use the `/** ... */` comment style (instead of `///`).
+- Use `@ref` when referencing other classes, functions, etc. in the Cesium Native API.
+- Use proper capitalization, grammar, and spelling.
+- Use back apostrophes (`) to encapsulate references to types and variable names.
+- Use triple back apostrophes (```) to encapsulate any snippets of math or code.
+
+You can optionally use `@snippet` to include examples of how functions are used in other parts of the code (usually test cases). First, surround the target code with comments containing a descriptive name:
+
+```cpp
+// In TestPlane.cpp...
+
+TEST_CASE("Plane constructor from normal and distance") {
+  //! [constructor-normal-distance]
+  // The plane x=0
+  Plane plane(glm::dvec3(1.0, 0.0, 0.0), 0.0);
+  //! [constructor-normal-distance]
+}
+```
+
+Then reference the file and the name of the snippet:
+
+```cpp
+/**
+ * @brief Constructs a new plane from a normal and a distance from the origin.
+ * 
+ * Example:
+ * @snippet TestPlane.cpp constructor-normal-distance
+ */
+Plane(const glm::dvec3& normal, double distance);
+```
+
+If you find that comments are duplicated across multiple classes, functions, etc., then:
+
+- Keep the comment on the most sensible instance, e.g., a base class or a pure virtual function.
+- Use `@copydoc` for the others.
+
+For `@copydoc`, keep the comment to one line instead of adding the usual linebreak after `/**`.
+
+```cpp
+/** @copydoc Foo */
+struct Bar { ... }
+```
+
+> Although private classes and functions aren't required to have the same level of documentation, it never hurts to add any, especially if they have non-obvious assumptions, scope, or consequences.
+
 ## 🗂️ Other
 
 Not covered by C++ Core Guidelines.