Re: SPITupleTable members missing in docs
Hello Daniel, Since this makes the number of internal members far outnumber the public ones, also reword the statement about which fields can be used to try and improve clarity. Patch applies cleanly, doc build ok. To take into account Tom's comment, I'd suggest a middle ground by commenting a public and private part explicitely in the struct, something like: typedef struct { /* PUBLIC members to be used by callers ... */ ... ... /* PRIVATE members, not intended for external usage ... */ ... } ... ; Another option would be to use some python-like naming convention on such members, eg with a leading underline character. Even if it is redundant with the paragraph below, it would make things visually clear as well. Note: I'm probaly not a member of the pgdoc list, so the delivery may fail there. -- Fabien.
Re: SPITupleTable members missing in docs
Hello, To take into account Tom's comment, I'd suggest a middle ground by commenting a public and private part explicitely in the struct, typedef struct { /* PUBLIC members to be used by callers ... */ /* PRIVATE members, not intended for external usage ... */ } ... ; One problem is that the members we've retroactively decided are "public" are in the middle of the struct :-(. Argh, I did not notice this tiny but relevant detail. But it occurs to me that there's no good reason we couldn't re-order the members, as long as we only do so on HEAD and not in released versions. That would make it a bit less inconsistent and easier to add labels such as you suggest. Indeed. SPI-dependent extensions are likely recompiled between major version, so a reordering should not cause significant problems. This mean that a simple doc patch is turned into a code patch. -- Fabien.
Re: SPITupleTable members missing in docs
Hello Daniel, I quite like this suggestion, so I’ve changed the patch to do this. Removed the doc: in the commit message to indicate that this is no longer just touching documentation. And it should be posted to . -- Fabien.
Re: SPITupleTable members missing in docs
I quite like this suggestion, so I’ve changed the patch to do this. Removed the doc: in the commit message to indicate that this is no longer just touching documentation. About v2: applies cleanly, compiles, make check and doc gen ok. However, the documentation does not look right, field comments are not aligned. Do not use tabs in the sgml file, use spaces only, otherwise the display layout is left to chance. -- Fabien.
Re: SPITupleTable members missing in docs
I quite like this suggestion, so I’ve changed the patch to do this. Removed the doc: in the commit message to indicate that this is no longer just touching documentation. About v2: applies cleanly, compiles, make check and doc gen ok. However, the documentation does not look right, field comments are not aligned. Do not use tabs in the sgml file, use spaces only, otherwise the display layout is left to chance. Of course, that was me fat-fingering. Fixed in the attached v3. Thanks for reviewing! V3 fixes the html display alignment issue. Patch marked as ready. -- Fabien.
Re: Another modest proposal for docs formatting: catalog descriptions
Hello Tom, oid oid Row identifier adrelid oid (references pg_class.oid) The table this column belongs to adnum int2 (references pg_attribute.attnum) The number of the column adbin pg_node_tree The column default value, in nodeToString() representation. Use pg_get_expr(adbin, adrelid) to convert it to an SQL expression. Thoughts? +1 My 0.02€: I'm wondering whether the description could/should match SQL syntax, eg: oid OID adrelid OID REFERENCES pg_class(oid) adnum INT2 REFERENCES pg_attribute(attnum) … Or maybe just uppercase type names, especially when repeated? oid OID adrelid OID (references pg_class.oid) adnum INT2 (references pg_attribute.attnum) … I guess that reference targets would still be navigable. -- Fabien.
Re: Another modest proposal for docs formatting: catalog descriptions
Hello Tom, oid OID Meh. I'm not a fan of overuse of upper case --- it's well established that that's harder to read than lower or mixed case. And it's definitely project policy that type names are generally treated as identifiers not keywords, even if some of them happen to be keywords under the hood. I found "oid oid" stuttering kind of strange, hence an attempt at suggesting something that could distinguish them. The markup I had in mind was for the field name and for the type name, but no decoration beyond that. Ok. If they are displayed a little differently afterwards that'd may help. As for the references, it seems to me that your notation would lead people to think that there are actual FK constraints in place, which of course there are not (especially not on the views). In practice the system ensures that the target exists, so it is as-if there would be a foreign key enforced? My point is that using differing syntaxes for the more-or-less the same concept does not help user understand the semantics, but maybe that is just me. I'm not hugely against it but I prefer what I suggested. Ok! -- Fabien.
Re: Another modest proposal for docs formatting: catalog descriptions
Hello Tom, Here's a more fully fleshed out draft for this, with stylesheet markup to get extra space around the column type names. I find this added spacing awkward, espacially as attribute names are always one word anyway. I prefer the non spaced approach. If spacing is discussed, should the layout rather try to align type information, eg: attributetype description --- foo bla this does this and that ... and here is an example about it --- foo-foo-foo bla-bla whatever bla bla blah bla foo foo foo ... and stuff I'm not sure how achievable it is from a xml & processing point of view, and how desirable it is, I'm just throwing it for consideration. -- Fabien.
Re: Another modest proposal for docs formatting: catalog descriptions
Hello Tom, Here's a more fully fleshed out draft for this, with stylesheet markup to get extra space around the column type names. I find this added spacing awkward, espacially as attribute names are always one word anyway. I prefer the non spaced approach. It's certainly arguable that that look is too heavy-handed. In the attached, I knocked down the extra space from 1em to 0.25em, which makes it quite a bit subtler --- are you any happier with this? Yes, definitely. BTW, I don't think it's very accurate that "attribute names are always one word" --- see the second attachment. Indeed. Here if anything I'm wanting a little more space. I'm fine with 0.25em which allows some breathing without looking awkward. Maybe a little more would still be okay, but not much more. If spacing is discussed, should the layout rather try to align type information, eg: I thought about that, but it seems extremely close to some of the earlier function-table layouts that were so widely panned. The SGML source would have to be a lot uglier too, probably with explicit use of spanspec's on every row. Hmmm, that's the kind of things I was afraid of. It could be done no doubt, but I think people would not see it as an improvement. Possibly. I'm a little at odds with Type not being above types, but far on the left, so that you cannot really "see" that it is about the format, especially with long attribute names: Column Type Description quite_a_long_attribute and_its_type ... The horizontal distance between "Type" and "and_its_type" is so wide as to hide the clue that the former is describing the later. But maybe aligning would be too ugly. If I can suggest more adjustements, maybe the description margin is a too much, I'd propose reduce it to about 3 chars wide. Obviously any aesthetic opinion is by definition subjective and prone to differ from one person to the next… -- Fabien.