CODE инструмент для создания документации для Delphi

Возможные Дублировать:
Code documentation for delphi similar to javadoc or c# xml doc CODE инструмент для создания документации для Delphi

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

(* Description of the function    
@param S  some string 
@param Index the index of string s 
@retval TRUE condition where it is true 
@retval FALSE otherwise. 
@see   IndexOf 
@see   Sort 
@see   Sorted 
*) 
bool Stringlist::Find(const char *S, int &Index) 
{ 
    [...] 
}

Является ли это лучшим способом для выполнения значимой документации для моего проекта? Если да, то какая хорошая программа для обработки этих типов комментариев. До сих пор мне рекомендовали Doc-O-Matic.

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

источник

2011-02-08 Daisetsu

Записываете ли вы приложение или его код? –

Я документирую код – Daisetsu

Возможный дубликат http://stackoverflow.com/questions/236047/code-documentation-for-delphi-similar-to-javadoc-or-c-xml-doc – rsenna

Посмотрите на SynProject, инструмент с открытым исходным кодом, написанный на Delphi.

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

Для документа архитектуры исходный код может извлекать комментарии (ala JavaDoc), а затем вставлять этот текст в основной документ архитектуры (с диаграммами иерархии классов и зависимостями блоков).

Вы пишете текстовый файл с использованием википодобного синтаксиса в выделенном текстовом редакторе, тогда SynProject создает из него хорошо сформированные документы Word. Некоторые Мастера доступны для доступа к контенту. Но поскольку он хранится как обычный файл, на нем могут записываться несколько программистов, используя любой инструмент SCM (SVN, Fossil ...).

Например, в настоящее время я использую его для написания документации по обслуживанию для огромного и старого приложения Delphi (около 2000 копий кода, написанного на Delphi 5 и 6), без предварительной документации. Вы описываете изменения, внесенные в код (путем цитирования unit/class/method), затем инструмент обновит все документы, чтобы отразить и проследить эти изменения. SynProject был разработан с учетом некоторых очень «деликатных» правил регулирования (IEC 62304), но может использоваться для любого проекта из-за его уникальной «плоской» конструкции.

источник

2011-02-08 20:12:53

-3

Если вы просто хотите документировать исходный код на основе комментариев функций, я бы рекомендовал вам использовать Doc-O-Matic.

Но настоящий вопрос здесь: следует ли документировать исходный код? Я так не думаю. Согласно TDD и XP, вы не должны комментировать свой код вообще. Ваш код должен содержать хорошие имена процедур, которые действительно показывают, что делает процедура. Поэтому вы можете подумать о том, чтобы не документировать его, просто реорганизовать его, чтобы его было легко понять.

источник

2011-02-08 20:41:46

Я знаю о больших проектах без документации и хорошо написанного кода: например, KSDev или MSEGui. И недостающая документация им жалко! Для крупных проектов комментарии кода или точная документация являются обязательными ИМХО. VCL не комментируется, но есть справочная справка. Кроме того, документирование интерфейсов также является хорошей практикой: я обычно пишу его, как если бы это была спецификация, а затем написал тест, а затем написал реализацию. Это отлично подходит для XP или TDD. Где вы узнали, что TDD или XP требует, чтобы вы не комментировали свой код! В TDD/XP нет догмы! –

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

Нет никаких «лучших способов» для создания документации в исходном коде. Следовательно, любой ответ будет субъективным в некоторой степени.

Прежде всего, вы должны выбрать стиль документирования в исходном тексте. Вы можете использовать либо «родные» комментарии, JavaDoc, либо XMLDoc. После выбора стиля документирования вы должны выбрать стандарты документирования.

Также вам нужен генератор документации для публикации документов в-источника (в HTML, PDF или другого формата)

Что касается исходного кода Delphi, в настоящее время JavaDoc стиль наиболее поддерживается. Я попробовал DelphiCodeToDoc (он использует JavaDoc) для генерации html-документации, и он работает. Я думаю, вы можете найти больше генераторов документации для источников Delphi, поддерживающих JavaDoc.

Еще предпочитаю XMLDoc стиль и Delphi Documentation Guidelines. Это субъективно. Я предполагаю, что лучший генератор документации Delphi теперь Doc-O-Matic. Он также поддерживает стиль JavaDoc, в настоящее время я экспериментирую с ним. Он не поддерживает все теги, упомянутые в Delphi Documentation Guidelines, например, он не поддерживает < лист >, но вы можете использовать <para> вместо этого и создать достоверную документацию.

Попробуйте то, что доступно, и выберите то, что вам больше нравится.

источник

2011-02-08 20:52:48 kludg

CODE инструмент для создания документации для Delphi

ответ

Смежные вопросы