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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Sep 27, 2018, 23:27 UTC
Message-ID: <20180927232732.GA216193@aiede.svl.corp.google.com>
In-Reply-To: <20180927212727.128214-1-sbeller@google.com>

Hi,

Stefan Beller wrote:

> There are different opinions on how to document an API properly.
> Discussion turns out nobody disagrees with documenting new APIs on the
> function level in the header file and high level concepts in
> Documentation/technical, so let's state that in the guidelines.

I disagree with this. I think we should put all the API docs in the header file, like we're already doing in e.g. strbuf.h.

Do you have a link to where in the discussion this split-docs strategy was decided?

Thanks, Jonathan

$ 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.