После завершения работы над очередным проектом наступает самый тяжкий период — написание документации и описания. Одно из моих правил документации — это наличие в начале файла комментария-выдержки с описанием всех функций. И создание этого комментария всегда выводило меня. Поэтому решил автоматизировать процесс.
Обычно во время разработки оставляю комментарий непосредственно над функцией. Но после завершения всей работы необходимо продублировать список всех функций комментарием в начало файла. Это позволит ускорить разработку в дальнейшем. Именно для этого создал форму выше. Закладываете в неё код и получаете структурированное описание функций. Покажу на примере.
Допустим, есть файл со следующими функциями проекта (именно в таком формате):
// вернёт путь к дефолтному аватару
function DefaultAvatar(){
…
}
// вернёт массив — имя и слоган пользователя
function UserInfoById($uid){
…
}
// вернёт url к аватару пользователя + ресайзнет
function UserPicById($uid, $picSize){
…
}
Чтобы форма сработала, необходимо идентичное форматирование. Одной строкой комментарий, обозначенный через //. И следующей строкой функция.
Если пропустить функции из цитаты через форму выше, то результат будет следующий:
/* — Функции в этом файле —
DefaultAvatar() — вернёт путь к дефолному аватару
UserInfoById($uid) — вернёт массив — имя и слоган пользователя
UserPicById($uid, $picSize) — вернёт url к аватару пользователя + ресайзнет
*/
Теперь можно скопировать результат и поставить в начало PHP файла.
К сожалению, пока не доходят руки сделать распознование функций внутри классов. Не представляю как поведёт себя форма, если поставить в неё подобный файл. Доделаю позже, если буду часто пользоваться этой формой…
P.S.
Форма доработана. Добавлена функция разделения на логические части. Теперь если новая строка начинается с конструкции «// ===»:
// вернёт массив — имя и слоган пользователя
function UserInfoById($uid){
…
}
// === функции работы с url адресами ======
// вернёт url к аватару пользователя + ресайзнет
function UserPicById($uid, $picSize){
…
}
То в результате строка логического разделения будет сохранена:
/* — Функции в этом файле —
UserInfoById($uid) — вернёт массив — имя и слоган пользователя
// === функции работы с url адресами ======
UserPicById($uid, $picSize) — вернёт url к аватару пользователя + ресайзнет
*/