From 27383a1929348daf01e18349f215c998b6ef8c2f Mon Sep 17 00:00:00 2001 From: Simon Ser Date: Wed, 25 May 2022 14:04:16 +0200 Subject: [PATCH] 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 --- CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65446c18..b67855cb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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