хитрая детализация

АНТОН ПАЛАГИН AKA TONY

Спецвыпуск: Хакер, номер #071, стр. 071-038-3

[создавай титульную страницу.]

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

[используй graphwiz.]

Если ты хочешь, чтобы в твоей документации были красивые графики и UML-диаграммы, скачай и установи утилиту graphwiz. Далее тебе необходимо на закладке Dot (doxygen) поставить нужные галочки и указать путь к этой утилите. После чего на выходе ты получишь нужные диаграммы.

[используй тег brief.]

В doxygen этот тег позволит тебе задавать краткое описание твоего метода, которое будет отображаться, когда методы класса показываются в одном большом списке.

[используй тег code.]

С помощью этого тега можно задавать примеры кода в твоей документации. Обрати внимание на отступы и форматирование кода примеров. Закрывается пример с помощью тега endcode.

[объединяй документацию.]

Если ты разрабатываешь несколько библиотек, то их документацию ты сможешь интегрировать при помощи механизма ссылок. Также существует возможность встраивать в документацию отдельные документы и изображения. Если немного поковыряться с тегами и настройками, то на выходе можно получить громадный талмуд документации со всеми нужными клиенту данными.

[рассмотри возможность использования LATEX.]

Этот формат позволяет использовать в тексте формулы. Если они тебе строго необходимы для документирования, то без LATEX не обойтись. Внутри тега \f можно задавать формулу с использованием формата LATEX. Этот тег будет проигнорирован, если в качестве выходного формата используется не LATEX. В общем, латекс рулит ;).

[используй различные схемы определения комментариев.]

Если ты активно используешь Rational Rose для дизайна архитектуры и постоянно делаешь форвард и реверс инжиниринг, то следует обратить внимание на то, что не все комментарии будут ей верно интерпретированы. Например, она проигнорирует символы «/*!», которые маркируют начало комментария для doxygen. Но если твои комментарии начинаются с последовательности «//!», то их роза будет добавлять в генерируемые файлы при форвард инжиниринге и вставлять в твои сущности модели при реверс инжиниринге. Таким образом, тебе не придется постоянно восстанавливать комментарии, и ты сможешь активно модифицировать свою модель и код.

WWW.STACK.NL/~DIMITRI/DOXYGEN/

HTTP://JAVA.SUN.COM/J2SE/JAVADOC/

HTTP://MSDN2.MICROSOFT.COM/EN-US/LIBRARY/B2S063F7.ASPX

WWW.GRAPHVIZ.ORG

ГЕНЕРАТОРЫ ДОКУМЕНТАЦИИ

HTTP://RU.WIKIPEDIA.ORG/WIKI/ГЕНЕРАТОР_ДОКУМЕНТАЦИИ

ГЕНЕРАТОР ДОКУМЕНТАЦИИ ГЛАЗАМИ ВИКПЕДИИ

WWW.INTERFACE.RU/BORLAND/BT2006.HTM

BORLAND TOGETHER 2006

ОПТИМАЛЬНЫМ СЧИТАЕТСЯ СООТНОШЕНИЕ СТРОК КОДА К СТРОКАМ КОММЕНТАРИЕВ - 1/3 И 1/4

СТОИМОСТЬ ВЛАДЕНИЯ ИСХОДНЫМ КОДОМ УМЕНЬШАЕТСЯ ПРЯМО ПРОПОРЦИОНАЛЬНО КОЛИЧЕСТВУ И КАЧЕСТВУ КОММЕНТАРИЕВ

ЕСЛИ ХОЧЕШЬ, ЧТОБЫ В ТВОЕЙ ДОКУМЕНТАЦИИ БЫЛИ КРАСИВЫЕ ГРАФИКИ И UML- ДИАГРАММЫ, СКАЧАЙ И УСТАНОВИ УТИЛИТУ GRAPHWIZ