Horton

Re: documentation structure

Corey Huinker <corey.huinker@gmail.com>

View thread
From: Corey Huinker <corey.huinker@gmail.com>
To: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Cc: Andres Freund <andres@anarazel.de>, Tom Lane <tgl@sss.pgh.pa.us>, Andrew Dunstan <andrew@dunslane.net>, Robert Haas <robertmhaas@gmail.com>, "pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Date: 2024-04-18T17:51:10Z
Lists: pgsql-hackers

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. docs: Consistently use <optional> to indicate optional parameters

  2. docs: Consolidate into new "WAL for Extensions" chapter.

  3. freespace: Don't return blocks past the end of the main fork.

  4. docs: Merge separate chapters on built-in index AMs into one.

  5. docs: Demote "Monitoring Disk Usage" from chapter to section.

  6. doc: move system views section to its own chapter

>
> I havent dealt with variadic yet, since the two styles are visually
> different, not just markup (<optional>...</optional> renders as [...]).
>
> The two styles for variadic are the what I call caller-style:
>
>    concat ( val1 "any" [, val2 "any" [, ...] ] )
>    format(formatstr text [, formatarg "any" [, ...] ])
>

While this style is obviously clumsier for us to compose, it does avoid
relying on the user understanding what the word variadic means. Searching
through online documentation of the python *args parameter, the word
variadic never comes up, the closest they get is "variable length
argument". I realize that python is not SQL, but I think it's a good point
of reference for what concepts the average reader is likely to know.

Looking at the patch, I think it is good, though I'd consider doing some
indentation for the nested <optional>s to allow the author to do more
visual tag-matching. The ']'s were sufficiently visually distinct that we
didn't really need or want nesting, but <optional> is just another tag to
my eyes in a sea of tags.