diff options
| -rw-r--r-- | runtime/doc/dev_style.txt | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt index ee8a2a3c3b..05dc727130 100644 --- a/runtime/doc/dev_style.txt +++ b/runtime/doc/dev_style.txt @@ -41,6 +41,43 @@ All header files should start with `#pragma once` to prevent multiple inclusion. #pragma once < +Headers system ~ + +Nvim uses two types of headers. There are "normal" headers and "defs" headers. +Typically, each normal header will have a corresponding defs header, e.g. +`fileio.h` and `fileio_defs.h`. This distinction is done to minimize +recompilation on change. The goal is to achieve the following: + +- All headers (defs and normal) must include only defs headers, system + headers, and generated declarations. In other words, headers must not + include normal headers. + +- Source (.c) files may include all headers, but should only include normal + headers if they need symbols and not types. + +Use the following guideline to determine what to put where: + +Symbols: + - regular function declarations + - `extern` variables (including the `EXTERN` macro) + +Non-symbols: + - macros, i.e. `#define`. + - static inline functions, but only if its function declaration has a + `REAL_FATTR_ALWAYS_INLINE` attribute. + - typedefs + - structs + - enums + + +- All symbols must be moved to normal headers. + +- Non-symbols used by multiple headers should be moved to defs headers. This + is to ensure headers only include defs headers. Conversely, non-symbols used + by only a single header should be moved to that header. + +- EXCEPTION: if the macro calls a function, then it must be moved to a normal + header. Constants ~ |