Техническая документация на уровне программных объектов, на мой взгляд, может быть нужна в двух случаях:
- Сопровождение компонентов, передаваемых сторонним разработчикам. В основном это коммерческие компоненты.
- Как внутренняя документация для команды разработчиков.
В первом случае документация фактически является хэлпом - она должна содержать информацию только о public объектах, должна быть соответственно структурирована и оформлена. Информация должна быть подробной – что объект делает, параметры вызова, особенности использования, где расположен (к какому юниту относится), от кого отнаследован. При этом расположение и иерархия являются вторичной информацией и не должны сильно бросаться в глаза.
Во втором варианте документация нужна для быстрого ознакомления с интерфейсами, функционалом и взаимодействием классов. Для более подробной информации есть код (который должен быть хорошо откомментирован). Т.е. подход почти диаметрально противоположный первому варианту. Информация должна быть краткой, и первичным становится расположение объектов.
Меня интересует второй случай. На текущий момент у нас используются обычные комментарии в объявлении классов, переменных, констант и т.д., и для ознакомления с функционалом юнита достаточно просмотреть его interface. Для упрощения взаимодействия между разработчиками и избавления от лишней информации (например вспомогательных переменных) хочется иметь возможность выгружать в отдельный файл объявления классов, всех public и protected членов класса с комментариями к ним и из protected членов класса только те, у которых есть комментарии. Это в идеале. С другой стороны задача, для нас, стоит не очень остро и дополнительных сил на написание своего парсера тратить не имеет смысла. Использование сторонних автоматических документаторов требует изменения формата комментариев и, соответственно, дополнительного контроля за правильностью их написания, что так же не имеет смысла.
Поэтому на генерацию XML документации в Turbo Delphi возлагались некоторые надежды. Были ожидания что с минимальными изменениями к требованиям к коментариям можно будет выгружать интерфейсы в читабельный вид. С другой стороны были опасения что или генератор будет глючить, или реализован будет так, что использовать его будет неудобно. К сожалению сбылись опасения.
В Turbo Delphi есть 2 варианта генерации XML документации:
- При компиляции приложения создается XML файл для каждго юнита и файла проекта. Для этого должна быть включена опция "Generate XML Documentation" на закладке "Compiler" в "Project Options".
- Можно создать единую документацию по всем исходникам приложения. Для этого должен быть включен "Together Support", а сама документация создается из "Model View".
В документацию идет вся информация по объектам + пользовательские комментарии (перед XML комментариями в коде должно быть ///). Вроде бы все хорошо, но…
Документация, создаваемая через "Model View" слишком "тяжелая". Ее, наверно, можно было бы использовать в качестве хэлпа для сопровождения компонентов, но там слишком много внутренней информации, которая в данном случае не нужна. Выбрать же уровень детализации (какие объекты выгружать в документ) нельзя. Насколько корректно работает данный генератор не проверялось т.к. стало ясно, что этот вариант генерации использоваться не будет.
Документация, создаваемая при компиляции на первый взгляд выглядела практически тем что надо. Основная проблема виделась в том, что для класса в XML файл тянется много избыточной информации: все данные по всем предкам. Для пустой формы это более чем 2000 (две тысячи)! строк. Но, в принципе, это не страшно т.к. при парсинге XML избыточную информацию можно игнорировать.
Начинаем экспериментировать с генерацией XML документации при компиляции:
1. Создаем простенький класс с одной функцией. XML комментарии сделаны перед объявлением класса, объявлением функции и в теле функции (последний был добавлен чтоб проверить не добавляет ли генератор комментарии из тела функции к комментариям к самой функции).
...
Получаем XML (комментарии подчеркнуты красным, предки свернуты, чтоб не мешаться). Комментарий из тела функции проигнорироаван, но это не страшно.
2. Добавляем процедуру с комментарием перед объявлением, тело процедуры без комментариев.
Получаем XML с перепутанными комментариями. Вместо комментария к процедуре вставился комментарий из тела функции
3. Ну если не нравятся генератору комментарии в implementation уберем комментарий из тела функции, но добавим один после всех объявлений.
...
И опять получаем XML с перепутанными комментариями.
Нет ребята, такой документатор использовать нельзя. А жаль, такая идея хорошая...
RSS Feed / Subscribe