Формат комментариев к БД — различия между версиями
Admin (обсуждение | вклад) (Новая страница: « Категория:Postgresql») |
Admin (обсуждение | вклад) |
||
| Строка 1: | Строка 1: | ||
| + | <span id="как-писать-комментарий"></span> | ||
| + | = Как писать комментарий = | ||
| + | |||
| + | Первой строчкой должно быть описание на русском одной короткой фразой о том, что содержит таблица.<br /> | ||
| + | Далее можно детализировать описание. | ||
| + | |||
| + | Если данные в таблицу добавляются (удаляются, модифицируются) '''автоматически''' (через триггер или функцию), то обязательно укажите об этом. | ||
| + | |||
| + | |||
| + | |||
| + | <span id="тэги-javadoc"></span> | ||
| + | = Тэги javadoc = | ||
| + | |||
| + | При описании следует использовать стандартные теги javadoc: | ||
| + | |||
| + | @author Обязательно!<br /> | ||
| + | @see<br /> | ||
| + | @deprecated | ||
| + | |||
| + | дополнительные тэги: | ||
| + | |||
| + | @create_dt дата создания таблицы, столбца, функции<br /> | ||
| + | @dev заметки для разработчиков. Текст под данным тэгом не будет попадать в документацию, передаваемую сторонним разработчиками.<br /> | ||
| + | @history история изменения см ниже | ||
| + | |||
| + | @todo аналог тэга @dev | ||
| + | |||
| + | <span id="соглашение-о-тэге-history"></span> | ||
| + | = Соглашение о тэге @history = | ||
| + | |||
| + | Пишем в таком формате | ||
| + | |||
| + | <pre class="">{@history | ||
| + | 2022-03-28 ZhukovYV Таблица создана | ||
| + | 2022-04-21 IvanovII Добавлено поле | ||
| + | }</pre> | ||
| + | |||
| + | |||
| + | <span id="чего-не-нужно-делать"></span> | ||
| + | = Чего не нужно делать = | ||
| + | |||
| + | * Начинать со слова "Таблица" | ||
| + | * Точки вконце | ||
| + | |||
| + | Вместо: | ||
| + | |||
| + | <code>Таблица типов мед. карт для сопоставления с Гаммамедом.</code> | ||
| + | |||
| + | Следует писать: | ||
| + | |||
| + | <code>Типы мед. карт для сопоставления с Гаммамед</code> | ||
| + | |||
| + | <span id="пример"></span> | ||
| + | = Пример = | ||
| + | |||
| + | <pre class="">Информация об авторе и последнем разработчике, изменившем процедуру | ||
| + | Заполняется триггером БД 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</pre> | ||
[[Категория:Postgresql]] | [[Категория:Postgresql]] | ||
Текущая версия на 09:00, 15 августа 2022
Содержание
Как писать комментарий
Первой строчкой должно быть описание на русском одной короткой фразой о том, что содержит таблица.
Далее можно детализировать описание.
Если данные в таблицу добавляются (удаляются, модифицируются) автоматически (через триггер или функцию), то обязательно укажите об этом.
Тэги 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
