Missing comments for tables and columns

[lbartoletti]

Tables: 48 Columns: 2962

Some comments can be easy to introduce 'id, geometry, short_XX, etc.'

Maybe travis can warn on this metric - like a coverage doc - and refuse new table or column without comment?

[lbartoletti]

This is a must have for the data dictionnary

[tudorbarascu]

I agree that we should improve the column/tables comments.

[lbartoletti]

@haubourg @elemoine What do you think about adding control over the new tables, where each column must have a comment to make travis happy?

[lbartoletti]

Quick test. Today we have 23 tables without comment

SELECT t.schemaname,
       t.tablename,
       pg_catalog.obj_description(c.oid)
FROM pg_catalog.pg_tables t
LEFT JOIN pg_catalog.pg_class c ON t.tablename = c.relname
WHERE t.schemaname LIKE 'qwat%'
  AND pg_catalog.obj_description(c.oid) IS NULL

[lbartoletti]

For columns

SELECT pg_tables.schemaname,
       pg_tables.tablename,
       pg_attribute.attname AS field,
  (SELECT col_description(pg_attribute.attrelid, pg_attribute.attnum) ) AS comment
FROM pg_tables,
     pg_class
JOIN pg_attribute ON pg_class.oid = pg_attribute.attrelid
AND pg_attribute.attnum > 0
WHERE pg_class.relname = pg_tables.tablename
  AND pg_attribute.atttypid <> 0::oid
  AND schemaname LIKE 'qwat%'
ORDER BY 1,2, attnum ASC

Only 44/980 have comments

[haubourg]

mm, that's quite a work to add all those comments. I've been playing a lot with pgmodeler to document the data model, I think I could help here, but we talks about several dozen of hours here

[lbartoletti]

It is necessary to proceed by steps. First, I think of commenting on all the tables and requiring that the new tables or views have a description.

We will see later on for the columns.

[sjib]

The SIA405 Norm 2015 has a lot of descriptions for the whole water model - it would be anyway good to document how the qwat model connects to this standard.

[haubourg]

@sjib Agreed! From what I get from @3nids, there is no direct relation with the SIA Norm. I've been working to evaluate the interoperability of the QWAT's Model with other models about 2 years ago. One blocker to me was that it is not easy to refer to the SIA models, UML schema and data dictionnary because it's not an open document. In which extent can we reuse parts of the SIA docs to publish some (open) documents ?