Хочется внедрить некий генератор документации кода. Конечно, хотелось бы просто взять один из них и включить чтобы оно заработало, но есть у нас несколько проблем, чтобы можно было оставить свой мозг в покое и не мучать его интеграцией всего этого дела.
Первая и основная проблема — текущий проект представляет собой веб-приложение. В нем используется два языка. JavaScript для клиентской части и PHP для серверной. Необходимо чтобы документация была сделана и для серверной и для клиентской части. По большому счету ничто, кроме кошерности, не мешает использовать два различных генератора документации. Но хочется мне, дабы обе части проекта обрабатывались одинаково. Не хочется иметь различный внешний вид документации для разных частей одного проекта. Плюс у них наверняка будут различаться требования к синтаксису, что тоже нехорошо.
Вторая проблема — не умеют генераторы парсить JavaScript код. Я уже почти выбрал Doxygen, но пока я его не научу своей уличной JavaScript магии, я его банально не смогу использовать. Из альтернатив был найден такой зверек, как JsDocToolkit. Но и он заработал только почти. Хотя это уже показатель — я его еще никак не настраивал и комментариев в коде хороших мало.
Третья проблема — в серверной части не используется ООП практически никак. Но в любом случае уже давно висят планы по рефакторингу серверной части с использованием ООП. Возможно даже на питоне. Так что со временем эта проблема отпадет так-же. Тем паче что модульная структура там есть и сейчас. Проблем в рефакторинге возникнуть не должно.
Резюмируя. Покрутившись по различным их представителям, я остановился на Doxygen. Если верить обещаниям, его можно настроить для работы с языками, что он не поддерживает. Плюс сам по себе он выглядит мощнее других разработок, что порождает надежду на его гибкость.
К сожалению мощность и гибкость означают только одно — наверняка Doxygen очень сложен для освоения. А мне ещё объяснять зачем это все надо и почему нельзя это делать более простым способом. Попытавшись отыскать какой-нибудь русифицированный сайт про Doxygen, я не смог отыскать ничего подобного. Возможно кто-нибудь сможет мне подсказать что-нибудь адекватное? Или мне надо будет переводить английскую документацию, дабы внедрять и использовать сие решение?
По результатам внедрения обязательно отчитаюсь :)
Первая и основная проблема — текущий проект представляет собой веб-приложение. В нем используется два языка. JavaScript для клиентской части и PHP для серверной. Необходимо чтобы документация была сделана и для серверной и для клиентской части. По большому счету ничто, кроме кошерности, не мешает использовать два различных генератора документации. Но хочется мне, дабы обе части проекта обрабатывались одинаково. Не хочется иметь различный внешний вид документации для разных частей одного проекта. Плюс у них наверняка будут различаться требования к синтаксису, что тоже нехорошо.
Вторая проблема — не умеют генераторы парсить JavaScript код. Я уже почти выбрал Doxygen, но пока я его не научу своей уличной JavaScript магии, я его банально не смогу использовать. Из альтернатив был найден такой зверек, как JsDocToolkit. Но и он заработал только почти. Хотя это уже показатель — я его еще никак не настраивал и комментариев в коде хороших мало.
Третья проблема — в серверной части не используется ООП практически никак. Но в любом случае уже давно висят планы по рефакторингу серверной части с использованием ООП. Возможно даже на питоне. Так что со временем эта проблема отпадет так-же. Тем паче что модульная структура там есть и сейчас. Проблем в рефакторинге возникнуть не должно.
Резюмируя. Покрутившись по различным их представителям, я остановился на Doxygen. Если верить обещаниям, его можно настроить для работы с языками, что он не поддерживает. Плюс сам по себе он выглядит мощнее других разработок, что порождает надежду на его гибкость.
К сожалению мощность и гибкость означают только одно — наверняка Doxygen очень сложен для освоения. А мне ещё объяснять зачем это все надо и почему нельзя это делать более простым способом. Попытавшись отыскать какой-нибудь русифицированный сайт про Doxygen, я не смог отыскать ничего подобного. Возможно кто-нибудь сможет мне подсказать что-нибудь адекватное? Или мне надо будет переводить английскую документацию, дабы внедрять и использовать сие решение?
По результатам внедрения обязательно отчитаюсь :)
