werehuman
13.01.2011 10:37 lithium
python-sphinx ( http://packages.python.org/an_example_py... ) или doxygen ( http://www.stack.nl/~dimitri/doxygen/exa... ) ?
22 comments
recommend
bookmark
subscribeDo you really want to delete ?
- within threads
- within tags
- within users
автосгенерённая документация не нужна
o_O_o_O
почему же?
ААА!!! Четырёхглазый!
а зачем? кто её будет использовать? если программист, который будет работать с кодом, то он и по коду и free form комментариям поймёт что к чему, а всем остальным — не нужно
sphinx нативнее же.
нет нужна.
no u!
R!
ок. А если планируется внезапно в какой-то момент времени подключить нового прога? Ему читать все исходники?
алсо не забываем о гугле и его индексаторе.
ммм? поясни тупому
ему зафиксить пару багов и он сам ощутит код
хмхмхм. Спорно в общем-то
меня этот способ ни разу ещё не подвёл
ну не генеришь, так хотя бы комментарии в doxygen-style расставляешь?
нет, названия функций, классов и параметров просто использую говорящие сами за себя, ну и функции делаю короткими
поиск. Особенно по всяким reference-ам (которые, кстати, как раз генерятся на отличненько).
Юзер, желающий посмотреть доку по функции, или найти нужную функцию, или ещё чего-нибудь, идёт в гугл (не всегда, но часто). А гугл не индексирует сорсы, он индексирует html — и если у вас изначально документация пишется не в html, то его нужно генерить. А если её можно генерить из аннотаций в коде — так вообще же профит!
Аргумент про гугл, правда, немного неактуален для closed source.
Тогда может спасти xapian?
ну это уже детали. Акцент ведь на том, что автогенерированная документация нужна, поскольку удобоварима для поиска.
Да, аргумент в пользу doxygen. Он умеет uml генерировать. Черещ graphviz. Или просто диаграмму наследования классов. http://www.stack.nl/~dimitri/doxygen/exa...
хм, sphinx тоже умеет