Обсуждение: Soliciting Feedback on Improving Server-Side Programming Documentation

On 03/15/2016 10:02 AM, Corey Huinker wrote:

> 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'm aware that some of these APIs change frequently. In those cases, I
> suggest that we make note of that on the same page.

I think this is all great. You may find some automated assistance from 
doxygen.postgresql.org .

Sincerely,

JD


-- 
Command Prompt, Inc.                  http://the.postgres.company/                        +1-503-667-4564
PostgreSQL Centered full stack support, consulting and development.
Everyone appreciates your honesty, until you are honest with them.

On 03/15/2016 10:30 AM, Corey Huinker wrote:
>
> On Tue, Mar 15, 2016 at 1:19 PM, Shulgin, Oleksandr
> <oleksandr.shulgin@zalando.de <mailto:oleksandr.shulgin@zalando.de>> wrote:
>
>     There's also a good deal of README files in the source tree, so I
>     would add:
>
>     4. find src -name 'README*'
>
>
> That too. But README's don't show up (easily) in a google search, so
> they elude discovery. We should want to make discovery easy to the
> uninitiated.

I don't think anyone is arguing with you. I think we are trying to point 
you to sources for your project.

JD

-- 
Command Prompt, Inc.                  http://the.postgres.company/                        +1-503-667-4564
PostgreSQL Centered full stack support, consulting and development.
Everyone appreciates your honesty, until you are honest with them.

-- 
Álvaro Hernández Tortosa


-----------
8Kdata

Over the past few months, I've been familiarizing myself with postgres server side programming in C.

My attempts to educate myself were slow and halting. The existing server side programming documentation has some examples, but those examples didn't show me how do what I wanted to do, and my research-via-google was highly circular, almost always pointing back to the documentation I had already found lacking, or a copy of it.

Most of what I have learned I have culled from asking people on IRC, or bugging people I've met through user groups and PgConf. In all cases, people have been extremely helpful. However, this method is inefficient, because we're using two people's time, one of whom has to tolerate my incessant questions and slow learning pace. 

Furthermore, the helpful suggestions I received boiled down to:

1. The function/macro/var you're looking for is PG_FOO, git grep PG_FOO

2. Look in blah.c which does something like what you're trying to do

3. The comments in blah.h do a good job of listing and explaining this macro or that

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

#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?

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

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.

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.
• A list/table of the DatumGet* macros. I'm aware that many of them overlap/duplicate others. That'd be good to know too.
• 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
• 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.
• Examples and explanation of how PG_TRY()/PG_CATCH work. How to add context callbacks.
• Direct Function Calls
• A comparison of the two modes of writing SRF functions (Materialize vs multi-call)
• 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?

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'm aware that some of these APIs change frequently. In those cases, I suggest that we make note of that on the same page.

Because I'm still going through the learning curve, I'm probably the least qualified to write the actual documentation. However, I have a clear memory of what was hard to learn and I have the motivation to make it easier on the next person. That makes me a good focal point for gathering, formatting, and submitting the documentation in patch form. I'm volunteering to do so. What I need from you is:

• Citations of existing documentation in header files that could/should be exposed in our more formal documentation.
• Explanations of any of the things above, which I can then reformat into proposed documentation.
• A willingness to review the proposed new documentation 
• Reasoned explanations for why this is a fool's errand

You supply the expertise, I'll write the patch.

Thanks in advance.