После завершения работы над очередным проектом наступает самый тяжкий период - написание документации и описания. Одно из моих правил документации - это наличие в начале файла комментария-выдержки с описанием всех функций. И создание этого комментария всегда выводило меня. Поэтому решил автоматизировать процесс.
Обычно во время разработки оставляю комментарий непосредственно над функцией. Но после завершения всей работы необходимо продублировать список всех функций комментарием в начало файла. Это позволит ускорить разработку в дальнейшем. Именно для этого создал форму выше. Закладываете в неё код и получаете структурированное описание функций. Покажу на примере.
Допустим, есть файл со следующими функциями проекта (именно в таком формате):
// вернёт путь к дефолтному аватару
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 к аватару пользователя + ресайзнет
*/
