Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs

From: Martin Ågren <martin.agren@gmail.com>
Date: Sep 28, 2018, 19:47 UTC
Message-ID: <CAN0heSq4-CXo5dzWdeBiR8nFdRzc-+YXE6h4w7WuB8qEiSBf6g@mail.gmail.com>
In-Reply-To: <xmqq5zypefcp.fsf@gitster-ct.c.googlers.com>

On Fri, 28 Sep 2018 at 18:51, Junio C Hamano <gitster@pobox.com> wrote:

> We recommend documenting in the header over documenting near the
> implementation to encourage people to write the docs that are
> readable without peeking at the implemention.

s/implemention/implementation/

> - - When you come up with an API, document it.
> + - When you come up with an API, document it the functions and the

s/it the/the/

> +   structures in the header file that exposes the API to its callers.
> +   Use what is in "strbuf.h" as a model to decide the appropriate tone
> +   in which the description is given, and the level of details to put
> +   in the description.

Martin

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.