contributing: add section about documentation conventions

Document the existing conventions.

Use `mystruct.foo` instead of `mystruct::foo` because `::` is pretty
alien to C.

Instead of backticks, use a different format to reference declarations
in our docs:

    See foo().
    See struct foo.
    See union bar.
    See enum baz.
    See typedef meh.

This is inspired by the kernel's documentation style [1]. This format
has the upside of being pretty natural to write and read, and can be
automatically processed by documentation generators.

[1]: https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext
This commit is contained in:
Simon Ser 2022-05-25 14:04:16 +02:00 committed by Simon Zeni
parent f91f38b79a
commit 27383a1929

View file

@ -216,6 +216,19 @@ Try to keep the use of macros to a minimum, especially if a function can do the
job. If you do need to use them, try to keep them close to where they're being
used and `#undef` them after.
### Documentation
* Documentation comments for declarations start with `/**` and end with `*/`.
* Cross-reference other declarations by ending function names with `()`, and
writing `struct`, `union`, `enum` or `typedef` before types.
* Document fields which can be NULL with a `// may be NULL` comment, optionally
with more details describing when this can happen.
* Document the bits of a bitfield with a `// enum bar` comment.
* Document the `data` argument of a `struct wl_signal` with a `// struct foo`
comment.
* Document the contents and container of a `struct wl_list` with a
`// content.link` and `// container.list` comment.
### Example
```c