Меню
Что нового?

Программы облегчающие документирование

List2006

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

1) Есть ли программы которые на основе кода могли собрать все данные (классы, функции, глобальные переменные...)?
Подойдет даже грамотный редактор UML - если оттуда потом можно будет скопировать все данные, хотя лучше бы конечно какое-нибудь конкретное средство.

2) Есть ли программы облегчающие документацию (скажем генерирующие HTML-документации на базе моего какого-то ввода данных или что-то подобное)?

В общем буду рад любой Вашей информация по revers ingenering и документированию.
 

List2006

Новичок
флоппик написал(а):
phpDocumentor же
Нажмите для раскрытия...
Она по-моему только комментарии phpDoc удачно читает, остальные классы как бы не видит, по крайней мере у меня полностью собрать все данные не вышло.
Да и сам результат не очень нравится, на пустой (без phpDoc) файл излишки информации создает, при этом в излишки дизайна вставляет даже ссылка на официальное руководство, а ссылку на файл банально нету (и зачем в документации движка ссылка на описание генератора? о_0)

Да и хотелось бы набор утилит, а не просто генератор. Так как большая часть правки вручную (а это лесть в html).

PS может быть я не разобрался, но очень не понравилось что она делает, а лесть писать phpDoc не вариант для меня (только загромоздит и так тысячи строк).
 

tz-lom

Продвинутый новичок
если ты пропробуешь phpDoc то быстро поймёшь что он хорош
и не надо лезть в HTML , дока это текст, все красивости и оформление пускай делает машина, а ты сконцентрируйся на том что машина сделать не может
 

List2006

Новичок
Для генерации из кода довольно хорош doxygen, а не убогий phpDocumentor который парсит по 20 минут и черте что собирает (и не все).
Еще раз говорю мне нужна программа для создания документации, а не генерации phpDoc его там в коде нет! (я был бы рад если он там был), писать туда phpDoc я тоже не собираюсь (там мегабайты кода), поэтому нужна утилита для ручного ведения документации (в данном случае мне интересует задокументировать часто используемые элементы).
 
weregod

weregod

unserializer
List2006 написал(а):
нужна утилита для ручного ведения документации
Нажмите для раскрытия...
текстовый редактор
List2006 написал(а):
часто используемые элементы
Нажмите для раскрытия...
если нужно узнать частоту использования "элементов", то профайлер или статические анализаторы кода, смотря что имеется в виду
 

tz-lom

Продвинутый новичок
а что мешает вести phpDoc только для часто используемых элементов?
не знаешь какие это элементы? - запусти профилировщик
 
weregod

weregod

unserializer
и, кстати, ручное ведение документации более вредно, чем полезно, особенно для активной разработки.
pre-commit hooks для обеспечения невозможности недокументированного кода & автогенерация автодокументации рулят!
 

List2006

Новичок
и, кстати, ручное ведение документации более вредно
Нажмите для раскрытия...
Автодокументации захламляют код (комменты должны быть как подсказки, а не сочинение из 100 строк - это портит навигацию по коду).
Второе, в случае с веб, нужно вновь документированные (но не измененные алгоритмы) файлы заливать на сервер, чтобы синхронизировать с локальным хранилищем.
Отсюда статистически увеличивает вероятность ошибки.

Да и различие подходов (phpDoc, javaDoc, Qt-style...) требуют привязки к определенной программе (у php я понял только два варианта Doxygen и phpDocumentor).
Да и возрастающая сложность приводит к тому, что приходится не только код сопровождать но и "код" этой документации иначе парсер не сотворит нам часть документации в случае ошибки (в условиях что выдача лог это тонны не нужной информации, заметить ошибку и искать её там не слабое занятие).

Да и вообще как логику надо отделять от отображения, так и документацию надо отделять от кода.
 

aluh

Новичок
С помощью Doxygen вы можете вынести часть комментариев в отдельные файлы и расположить их в одном месте. Doxygen позволяет автоматически создавать хорошую документацию, но этим надо заниматься.
 
Absinthe

Absinthe

жожо
Автодокументации захламляют код (комменты должны быть как подсказки, а не сочинение из 100 строк - это портит навигацию по коду).
Нажмите для раскрытия...
Хочешь сказать, что не пользуешься автодополнением в IDE?
 
Absinthe

Absinthe

жожо
List2006 когда прекратите пользоваться редакторами для набора кода, производительность повысится.
Для ваших методов вам придется писать phpdoc комментарии, чтобы IDE могла верно подсказывать методы и проверять ошибки.
А документацию получите нахаляву через doxygen.

Неужели у вас нет желания получить документацию нахаляву?
 

List2006

Новичок
List2006 когда прекратите пользоваться редакторами для набора кода, производительность повысится.
Нажмите для раскрытия...
Мне не совсем понятно что такое "редакторы для набора кода"? И почему производительность повыситься?
Я пользуюсь IDE Netbeans и JavaDoc(doxygen).

На злобу фанатикам.
К сожаление phpDocumentor медленней в 15-25 раз, а сама нотация phpDoc - унылая пародия на javadoc.
 

List2006

Новичок
weregod написал(а):
Вот эти ребята используют DocBlox и не знают, что
Нажмите для раскрытия...
Полазил я на сайте проекта, документацию и примеры не нашел.
Мне нравятся когда создают что-то, что понимают только сами разработчики (забывая о самом важном - о документации) :)

Но меня порадовала надпись "DocBlox has merged with phpDocumentor to become phpDocumentor2..." То есть DocBlox пародия уже на PHPDoc :)

Видимо каждому хочется открыть казино со своим блэкджеком и ...
 
Войдите или зарегистрируйтесь для ответа.
Сверху