On Nov 17, 2013, at 1:52 PM, Leif Hedstrom <[email protected]> wrote: > What I think we need to do, assuming this is how we want to organize the > docs, is to have one section introducing the overall purpose of the set of > APIs, followed by <n> sections, one for each API, where each section > documents the function prototype and return type, as well as the usage. This > is how the old PDF documentation was laid out.
From the IRC discussion, the above does not fit within the man-page structure. Instead, I’d like to suggest that we group APIs with similar functionality, and very similar prototypes and return value semantics in each Sphinx file. For my example, I’m now back to creating one file named TSMimeHdrFieldValueStringGet.en.rst, with the following APIs documented in it: .. function:: const char* TSMimeHdrFieldValueStringGet(TSMBuffer bufp, ... .. function:: int TSMimeHdrFieldValueIntGet(TSMBuffer bufp, ... .. function:: int64_t TSMimeHdrFieldValueInt64Get(TSMBuffer bufp, ... .. function:: unsigned int TSMimeHdrFieldValueUintGet(TSMBuffer bufp, ... .. function:: time_t TSMimeHdrFieldValueDateGet(TSMBuffer bufp, … Set() functions, object creations etc. will have to go in separate docs (IMO at least). Most of the pages we have already falls within that guideline, but a few of them probably ought to get broken up into 2 or more files. E.g. TSUrlCreate.en.rst would be split up into one for “creation” of URLs (Create, Clone, Parse etc.), one for Set() methods and one for Get() methods. More thoughts ? — Leif
