Формат комментариев к БД

Как писать комментарий

Первой строчкой должно быть описание на русском одной короткой фразой о том, что содержит таблица.
Далее можно детализировать описание.

Если данные в таблицу добавляются (удаляются, модифицируются) автоматически (через триггер или функцию), то обязательно укажите об этом.

Тэги javadoc

При описании следует использовать стандартные теги javadoc:

@author Обязательно!
@see
@deprecated

дополнительные тэги:

@create_dt дата создания таблицы, столбца, функции
@dev заметки для разработчиков. Текст под данным тэгом не будет попадать в документацию, передаваемую сторонним разработчиками.
@history история изменения см ниже

@todo аналог тэга @dev

Соглашение о тэге @history

Пишем в таком формате

{@history
2022-03-28  ZhukovYV Таблица создана
2022-04-21  IvanovII Добавлено поле 
}

Чего не нужно делать

• Начинать со слова "Таблица"
• Точки вконце

Вместо:

Таблица типов мед. карт для сопоставления с Гаммамедом.

Следует писать:

Типы мед. карт для сопоставления с Гаммамед

Пример

Информация об  авторе и последнем разработчике, изменившем процедуру
Заполняется триггером БД pgevent_proc_doc
Можно проинициализировать данными (из комментариев и таблицы audit.postgresql_log_ddl) функцией dev.proc_doc_init 

@author ZhukovYV

@create_dt 2022-03-28

@history_dt  2022-04-07

{@history
2022-03-28  ZhukovYV Таблица создана
}

@see dev.proc_doc_init