readable. The following rules describe
what you should comment and where. But remember: while comments are very
important, the best code is self-documenting.

When writing your comments, write for your audience: the next contributor who
will need to understand your code. Be generous — the next one may be you!

Nvim uses Doxygen comments.


Comment Style ~

Use the `//`-style syntax only. >c

    // This is a comment spanning
    // multiple lines
    f();


File Comments ~

Start each file with a description of its contents.

    Legal Notice ~

    We have no such thing. These things are in LICENSE and only there.

    File Contents ~

    Every file should have a comment at the top describing its contents.

    Generally a `.h` file will describe the variables and functions that are
    declared in the file with an overview of what they are for and how they
    are used. A `.c` file should contain more information about implementation
    details or discussions of tricky algorithms. If you feel the
    implementation details or a discussion of the algorithms would be useful
    for someone reading the `.h`, feel free to put it there instead, but
    mention in the `.c` that the documentation is in the `.h` file.

    Do not duplicate comments in both the `.h` and the `.c`. Duplicated
    comments diverge. >c

    /// A brief description of this file.
    ///
    /// A longer description of this file.
    /// Be very generous here.


Struct Comments ~

Every struct definition should have accompanying comments that describes what
it is for and how it should be used. >c

    /// Window info stored with a buffer.
    ///
    /// Two types of info are kept for a buffer which are associated with a
    /// specific window:
    /// 1. Each window can have a different line number associated with a
    /// buffer.
    /// 2. The window-local options for a buffer work in a similar way.
    /// The window-info is kept in a list at g_wininfo.  It is kept in
    /// most-recently-used order.
    struct win_info {
      /// Next entry or NULL for last entry.
      WinInfo *wi_next;
      /// Previous entry or NULL for first entry.
      WinInfo *wi_prev;
      /// Pointer to window that did the wi_fpos.
      Win *wi_win;
      ...
    };

If the field comments are short, you can also put them next to the field. But
be consistent within one struct, and follow the necessary doxygen style. >c

    struct wininfo_S {
      WinInfo *wi_next;  ///< Next entry or NULL for last entry.
      WinInfo *wi_prev;  ///< Previous entry or NULL for first entry.
      Win *wi_win;       ///< Pointer to window that did the wi_fpos.
      ...
    };

If you have already described a struct in detail in the comments at the top of
your file feel free to simply state "See comment at top of file for a complete
description", but be sure to have some sort of comment.

Document the synchronization assumptions the struct makes, if any. If an
instance of the struct can be accessed by multiple threads, take extra care to
document the rules and invariants surrounding multithreaded use.


Function Comments ~

Declaration comments describe use of the function; comments at the definition
of a function describe operation.

    Function Declarations ~

    Every function declaration should have comments immediately preceding it
    that describe what the function does and how to use it. These comments
    should be descriptive ("Opens the file") rather than imperative ("Open the
    file"); the comment describes the function, it does not tell the function
    what to do. In general, these comments do not describe how the function
    performs its task. Instead, that should be left to comments in the
    function definition.

    Types of things to mention in comments at the function declaration:

    - If the function allocates memory that the caller must free.
    - Whether any of the arguments can be a null pointer.
    - If there are any performance implications of how a