mirror of
https://github.com/hyprwm/wlroots-hyprland.git
synced 2024-11-05 05:05:57 +01:00
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:
parent
f91f38b79a
commit
27383a1929
1 changed files with 13 additions and 0 deletions
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue