Re: Soliciting Feedback on Improving Server-Side Programming Documentation

On 16 March 2016 at 01:02, Corey Huinker <corey(dot)huinker(at)gmail(dot)com> wrote:

> #1 git grep is a helpful reflex for discovering examples on my own, but it
> requires that I have a term to search on in the first place, and too often
> I don't know what I don't know.
>

Yep. This can be painful when you're trying to figure out what macro to use
to access fields in some struct, the PG_GETARG macro for a type, etc.

> #2 is the gold standard in terms of correctness (the code had to have
> worked at least up to the last checkin date), and in terms of
> discoverability it often gave me names of new macros to search for, coding
> patterns, etc. However, I was always left with the questions: How would I
> have figured this out on my own? How is the next person going to figure it
> out? Why doesn't anybody document this?
>

Indeed. In particular, it's not always obvious when you're new to the
codebase which files relate to what. The codebase is fairly well structured
but you have to get a decent understanding of how the bits of the server
fit together before you really know where to look.

A src/README docs with brief descriptions of the tree structure and key
files would be helpful, or additions to src/DEVELOPERS .

> #3 Often answers the last question in #2: It *is* documented, but that
> documentation is not easily discoverable by conventional means.
>

Particularly when it's a comment on a function that you have to know about
before you can find the comment.

> So what I'd like to do is migrate some of the helpful information in the
> header files into pages of web searchable documentation, and also to revamp
> the existing documentation to be more relevant.
>

I'm not convinced by that part. Rather than moving stuff into the SGML
docs, which are frankly painful to maintain and less visible when editing
the relevant code, I'd be much happier to see README-style docs located
close to the code they're relevant to, and/or cross-referencing comments in
headers and sources to help tell you where to look.

Along the way, I collected a list of things I wished I'd had from the start:
>
> - A list of all the GETARG_* macros. It would have been especially
> great if this were in table form: Your Parameter Is A / Use This Macro /
> Which Gives This Result Type / Working example.
>
> Yes, though that's an area where "git grep" does a reasonable job it's a
bit awkward.

This probably *should* be in the SGML docs, in the C extensions section,
along with the related DatumGet and PG_RETURN_ functions and macros.

>
> - The table at
> http://www.postgresql.org/docs/9.1/static/errcodes-appendix.html has
> the numeric codes and PL/PGSQL constants enumerated. It'd be nice if it had
> the C #define as well
>
>
... at least where the C define is different to the plpgsql constant. Which
is occasonally the case.

>
> - The SPI documentation mentions most/all of the SPI functions, but I
> couldn't find documentation on the SPI variables like SPI_processed and
> SPI_tuptable.
>
> http://www.postgresql.org/docs/current/static/spi-spi-execute.html

>
> - Examples and explanation of how PG_TRY()/PG_CATCH work. How to add
> context callbacks.
>
> ... and warnings about their limitations. In particular, that PG_TRY /
PG_CATCH doesn't imply a savepoint and you can't just merrily carry on
after (say) an SPI error.

>
> - Direct Function Calls
>
> Yeah, with a few examples, including one showing caching of the fmgr info
for a FunctionCall by info not oid.

>
> - A comparison of the two modes of writing SRF functions (Materialize
> vs multi-call)
>
> Worthwhile, yeah.

>
> - Less explanation of how to do write V0-style functions. That was
> called the "old style" back in version 7.1. Why is that information up
> front in the documentation when so much else is sequestered in header files?
>
> I'd just like to delete that entirely.

Some of these things may seem obvious/trivial to you. I would argue that
> they're only obvious in retrospect, and the more obvious-to-you things we
> robustly document, the quicker we accumulate programmers who are capable of
> agreeing that it's obvious, and that's good for the community.
>

I still remember them being very non-obvious, so I agree.

> Because I'm still going through the learning curve, I'm probably the least
> qualified to write the actual documentation.
>

You're *extremely* qualified to make notes of what's hard, though, which is
something people who've worked on the codebase for a while tend to forget.

I've been trying to write little bits of docs as I go and as I learn.
Going to write one on how timelines work soon.

--
Craig Ringer http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services