Thread: Comments on all system objects

Hi,

Is there any reason I shouldn't submit a patch that makes it so that we 
have comments on 100% of the catalog objects?  I don't see any reason 
why we shouldn't do it...

Chris

Christopher Kings-Lynne <chriskl@familyhealth.com.au> writes:
> Is there any reason I shouldn't submit a patch that makes it so that we 
> have comments on 100% of the catalog objects?

Bulk?  Redundancy with the SGML documentation?

There are already more than enough places to have to edit documentation
when we change/add a column in a system catalog.  I don't see the value
of adding another, especially not one that's constrained to one line.
And what will comments on, say, system indexes contribute really?

I think we are fairly close to having some kind of comment on nearly all
the built-in functions and operators (though far too many of those
comments are useless boilerplate that we could just as well do without).
Cleaning up any omissions in that area doesn't seem like a bad project.
But I question the value of extending the policy to other sorts of
objects.
        regards, tom lane

Christopher Kings-Lynne wrote:
> Is there any reason I shouldn't submit a patch that makes it so that
> we have comments on 100% of the catalog objects?

The ability to comment on all types of catalog objects or actual 
comments on all predefined catalog objects?  Both are more or less 
reasonable.  But I think we should have some sort of 
internationalization mechanism for the actual comments.

> The ability to comment on all types of catalog objects or actual 
> comments on all predefined catalog objects?  Both are more or less 
> reasonable.  But I think we should have some sort of 
> internationalization mechanism for the actual comments.

One of my first commits for 7.5 was the format, I added being able to 
comment on about 5 new objects.  I intended the latter.  I guess I could 
clean up the functions and operators like Tom indicated, but that's all 
I'll do I guess.

Internationalisation...hmmm...I don't know how to do that.  Can you put 
gettext around the builtins stuff?

Chris

> Bulk?  Redundancy with the SGML documentation?
>
> There are already more than enough places to have to edit documentation
> when we change/add a column in a system catalog.  I don't see the value
> of adding another, especially not one that's constrained to one line.
> And what will comments on, say, system indexes contribute really?

Maybe it would not be that bad if the comments could be derived
automatically from the sgml documentation? At least for comments that are
not provided directly from the initialization phase?

That may involve designing a new tag for the sgml. Something like
<shortdescr>... to specify the object name, its type and its description,
so that some filter could derive the appropriate "COMMENT ON".

I appreciate having something to read on a "\d+" in psql, without having
to turn to the online doc.

-- 
Fabien Coelho - coelho@cri.ensmp.fr

Hi all,

> > The ability to comment on all types of catalog objects or actual
> > comments on all predefined catalog objects?  Both are more or less
> > reasonable.  But I think we should have some sort of
> > internationalization mechanism for the actual comments.
>
> One of my first commits for 7.5 was the format, I added being able to
> comment on about 5 new objects.  I intended the latter.  I guess I could
> clean up the functions and operators like Tom indicated, but that's all
> I'll do I guess.
>
> Internationalisation...hmmm...I don't know how to do that.  Can you put
> gettext around the builtins stuff?
>
Maybe design something like in psql. A perl script that grabs the help from an SGML document.

Internationalisation? Maybe when some groups provides the translation of an SGML.


--
Euler Taveira de Oliveira
euler (at) ufgnet.ufg.br
Desenvolvedor Web e Administrador de Sistemas
UFGNet - Universidade Federal de Goiás