CONTRIBUTING: Add basic docstring guidelines.

Fixes https://github.com/pybricks/pybricks-api/issues/99

CONTRIBUTING.md

@@ -42,6 +42,81 @@ will actually be implemented.
 
 [commits]: https://github.com/pybricks/pybricks-api/commits/master
 
+**General docstring principles:**
+
+The stubs libraries in this repository have two different purposes:
+1. Auto-generating documentation with Sphinx. For this purpose, the
+   documentation should be concise and clear.
+2. Provide autocomplete and intellisense in code editors. For this purpose,
+   the code needs to be 100% correct. This way, computers can parse your code
+   correctly and tell you when something is wrong.
+
+Since these objectives don't always align, we address these separately in the
+stubs library:
+
+1. The first line(s) of the docstring contain the function or method signature
+   as it should be displayed in the human-readable documentation.
+2. The real function signature can be as complex as it needs to be to make it
+   correct for intellisense. Overloads can be uses if needed.
+
+In the rare case where the docstring signature is the same as the typed
+version, we'll still include it for consistency.
+
+**Docstring details:**
+
+Make sure to look at existing function signatures and docstrings for
+inspiration when documenting new functionality. As an example, consider:
+
+```python
+def run_until_stalled(
+    self,
+    speed: Number,
+    then: Stop = Stop.COAST,
+    duty_limit: Optional[Number] = None,
+) -> int:
+    """
+    run_until_stalled(speed, then=Stop.COAST, duty_limit=None) -> int: deg
+
+    Runs the motor at a constant speed until it stalls.
+
+    Arguments:
+        speed (Number, deg/s): Speed of the motor.
+        then (Stop): What to do after coming to a standstill.
+        duty_limit (Number, %): Duty cycle limit during this
+            command. This is useful to avoid applying the full motor
+            torque to a geared or lever mechanism. If it is ``None``, the
+            duty limit won't be changed during this command.
+
+    Returns:
+        Angle at which the motor becomes stalled.
+    """
+```
+The real method signature at the top contains the full detail, including the
+type of each argument and return value.
+
+The docstring starts with the signature. Use more than one signature if needed
+to represent overloaded methods. The signatures are written in the way they
+should be displayed in the docs:
+- Argument types are omitted because they are also shown with the argument
+  description below.
+- Default values should be given (``then=Stop.COAST``).
+- The return type should be given (``-> int``). When applicable, include
+  the unit of the return value, so it becomes ``-> int: deg``
+
+Then follows a concise description of what this method, function, or class
+does.
+
+Then follows a list of arguments:
+- For each argument, include the expected type and unit if applicable, e.g.
+  ``(int)`` or ``(Number, deg/s)``.
+- Use ``Number`` when ``int`` and ``float`` are both allowed.
+- If the description is long, use the indentation shown above.
+- Make it readable. Instead
+  of ``Union[float, SupportsFloat, complex, SupportsComplex]``,
+  just say _float or complex_.
+
+Then follows a description of the return value. The type is omitted here since
+it is already include in the docstring signature.
 
 **Development environment:**