Полнота документации — новые классы не документированы. Басыров Роберт а не подскажете, какое сейчас покрытие документацией классов в процентном соотношении?
Скорость её обновления — разработчики пишут код, а не документацию к нему. Потом пытаются нагнать.
Отсутствие документации в формате phpDoc — тема для отдельного холивара, но некоторые просят )
Безумная пятничная идея 1. Берём модуль LiveAPI от Sharomov Denis — http://marketplace.1c-bitrix.ru/solut...x.liveapi/ и немного «подкрутив» его сохраняем результаты работы в ИБ. Т.е. нам надо что бы элементом ИБ был метод класса или обработчик события или константа.
Таким образом мы получаем кучу записей вида CDataXML::Load($file) которые можно разобрать программно до состояния вида:
Наименование метода и его человеческое название
Список аргументов и их типы
Тип возвращаемого результата
Т.е. мы получим элементы ИБ у которых будет много свойств и большая часть из них не будет заполнена.
2. Пишем парсер, который сможет распознавать структуру http://dev.1c-bitrix.ru/api_help/ и на запрос вида CIBlockElement::GetList будет делаться запрос по адресу модуль/classes/название класса/название метода.php и оттуда будет выдираться структура и документация по названию метода, свойствам, типу возвращаемых результатов.
3. Погоняв связку из модифицированного LiveAPI и парсера мы получим у себя частично заполненный массив ИБ.
Тут мы уже сможем:
оценить полноту документации по последней версии битрикса
видеть, какие элементы не заполнены или отсутствуют вообще в документации.
И самое главное — сможем нарисовать УДОБНЫЙ интерфейс по заполнению свойств у элементов ИБ. Т.е. у нас будет коллективная редактилка документации кем угодно из нашего сообщества. Естественно используя все прелести хранения данных в ИБ.
Соответственно можно просить сообщество дописывать документацию и отдавать эти дельты Роберту для вычитки и проверки.
С выходом новых версий Bitrix всё сведётся к переиндексации исходного кода модулей и получения нового списка правок.
Внезапный бонус от структурированного хранения документации — можно основательно подкрутить скрипт LiveAPI и заставить его модифицировать файлы ядра обогащая их комментариями в формате PHPDoc если кому то так уж это надо для красивых подсказок. Правда тут уже никто не застрахован от ошибок и гнева системы контроля целостности ядра Кажется меня сейчас забанят.
Риски
Некоторые плачут о том что документация плохая и её мало, но мало кто будет её писать.
Документация будет написана, но в ней будет масса ошибок.
что забыл?
Как можно взаимодействовать с сообществом и таки улучшить документацию.
Попросить принять посильное участие.
Сделать конкурс с раздачей призов.
Давать партнерские баллы.
Может придумаем ещё пяток вариантов как сделать нашу жизнь с Bitrix приятнее?
/**
* <p>Возвращает список элементов по фильтру <i>arFilter</i>.</p><p><b>Примечания</b>:</p><ol> <li>Внутренние ограничения Oracle и MSSQL не позволяют использовать DISTINCT при фильтрации по полям типа blob, поэтому фильтрация по нескольким значениям множественного свойства может дать дублирование. </li> <li>Поля перечисленные для сортировки будут автоматически добавлены в параметр arSelectFields или в arGroupBy, если указана группировка записей. <br> </li> </ol>
*
*
*
*
* @param array $arOrder = Array("SORT"=>"ASC") Массив вида Array(<i>by1</i>=><i>order1</i>[,
* <i>by2</i>=><i>order2</i> [, ..]]), где <i>by</i> - поле для
* сортировки, может принимать значения: <ul> <li> <b>id</b> - ID
* элемента; </li> <li> <b>sort</b> - индекс сортировки; </li>
...
...
* то для этого в массиве необходимо указать следующие <a
* href="http://dev.1c-bitrix.ru/api_help/main/general/ratings/hidden_components/rating_vote.php">поля</a>:
* RATING_TOTAL_VALUE, RATING_TOTAL_VOTES, RATING_TOTAL_POSITIVE_VOTES, RATING_TOTAL_NEGATIVE_VOTES,
* RATING_USER_VOTE_VALUE.</p>
*
*
*
* @return mixed <a
* href="http://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockresult/index.php">CIBlockResult</a>
*
*
* @tutorial <li> <a
* href="http://dev.1c-bitrix.ru/api_help/main/reference/cdbresult/index.php">CDBResult</a> </li>
*
*
* @static
* @link http://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/getlist.php
* @author phpDoc author - generator by hipot at 11.08.2012
*/
Далее этот комментарий вставляем перед GetList и получаем подсказки в IDE типа eclipse.
Сперва мы мыслили глобально (как описали Вы), но столкнулись с ситуацией, что все таки затраченное время будет напрасным в нашем случае. Ведь достаточно дать разработчику возможность генерировать шапку для необходимых ему методов и функций, а он уже сам нагенерирует себе phpDoc-шапку для часто используемых методов и функций.
При написании этого сервиса столкнулись со следующими трудностями: 1. различие формата в документации (теги, расположение, и проч.) т.е. не однотипность тегов, очень много пришлось писать фиксов во время разработки под частные отличия страниц. 2. все таки чтобы реализовать всю описанную вами схему, нужно парсить не только методы, но и страницы документации с константами и проч. они тоже должны комментироваться. 3. в справке очень часто параметры называется не так, как в исходном коде, напр. $stringCompare вместо $to_compare и проч.
Это все первое.
Второе: По генерации phpDoc кода в php файлах есть ряд библиотек, написанных на php. Так что это тоже решаемо, но, опять же, на сколько надо ли и какие задачи решит?
В принципе, все описанное вами возможно, но мы пришли к выводу что нам достаточно такого сервиса. Вот, к примеру, как в среде разработки у нас выглядит подсказка по такому phpDoc-комментарию в случае метода получения пользователей:
Процент в точности оценить не могу, требуется детальное сравнение. На мой взгляд - процентов 70 описано. По поводу нового - вы не правы. Документируется, даже выходит раньше функционала. Но не в тех объёмах, каких хотелось бы.
Сама по себе идея такого инструмента - хорошая. Она обсуждалась нами ранее, но разработчики выражали сомнение в качествености таких текстов. Обсудим ещё раз.
Да что говорить, если некоторый функционал принципиально не хотят публиковать уже лет 5, комментарии пользователей конечно хорошо, но порой там публикуют откровенный не проверенный бред. http://idea.1c-bitrix.ru/dokumentirov...-svoystva/ - как прокомментируют не желание публиковать документацию к тому что все пользуют?
Группы на сайте создаются не только сотрудниками «1С-Битрикс», но и партнерами компании. Поэтому мнения участников групп могут не совпадать с позицией компании «1С-Битрикс».