Как документировать использование базы данных с помощью PHPdoc?

Question

Теперь мне интересно, документируют ли другие использование базы данных в заголовках функций ... например, fn () может читать или записывать базу данных (или ее таблицу), или создавать, изменять или удалять базу данных или таблицу.(дополнительный вопрос: должен ли fn (), который изменяет базу данных с помощью «USE xxx», «помнить» текущую базу данных при входе и снова использовать ее перед выходом?)

Мне кажется, что такого рода вещи следует задокументировать, но как лучше это сделать?@uses или как?

Answer 1

Почему бы не использовать @link и список вместе со списком помощников:

/**
 * Some comments here.
 *
 * Helper functions:
 * * {@link someHelper}
 * * {@link theOtherHelper}
 *
 * Reads tables:
 * * {@link Table1}
 * * {@link Table2}
 *
 * Reads/Writes tables:
 * * {@link Table3}
 * * {@link Table4}
 */

Затем вы создаете несколько тематических страниц для этих таблиц с кратким описанием «Содержит параметры для бизнес-процесса X».