On Wed, Feb 3, 2016 at 8:00 PM, Kouhei Kaigai <kaigai@ak.jp.nec.com> wrote:
>> Well, looking at this a bit more, it seems like the documentation
>> you've written here is really misplaced. The patch is introducing a
>> new facility that applies to both CustomScan and ForeignScan, but the
>> documentation is only to do with CustomScan. I think we need a whole
>> new chapter on extensible nodes, or something. I'm actually not
>> really keen on the fact that we keep adding SGML documentation for
>> this stuff; it seems like it belongs in a README in the source tree.
>> We don't explain nodes in general, but now we're going to have to try
>> to explain extensible nodes. How's that going to work?
>>
> The detail of these callbacks are not for end-users, administrators and
> so on except for core/extension developers. So, I loves idea not to have
> such a detailed description in SGML.
> How about an idea to have more detailed source code comments close to
> the definition of ExtensibleNodeMethods?
> I haven't seen the src/backend/nodes/README yet, and it has only 6 updates
> history from Postgres95 era. I guess people may forget to update README
> file if description is separately located from the implementation.
Hmm, that might work, although that file is so old that it may be
difficult to add to. Another idea is: maybe we could have a header
file for the extensible node stuff and just give it a really long
header comment.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company