Как я могу создать файл справки CHM на основе комментариев исходной документации?

Возможный дубликат:
Документация по коду для delphi, аналогичная javadoc или c# xml doc

Я использовал возможности документирования RAD Studio Delphi XE2 в большинстве своих глобальных источников (библиотеки, такие как бизнес-правила, компоненты/элементы управления и т. д.). Это помещает некоторый закомментированный текст непосредственно перед объявлением различных вещей в вашем исходном коде, например:

type
  ///   <summary>
  ///     This class is used for this and that.
  ///   </summary>
  TMyObject = class(TObject)
  ....

или даже

/// <summary>
///   This function does this and that.
/// </summary>
/// <returns>
///   This is the result of what DoSomething produces.
/// </returns>
/// <remarks>
///   DoSomething is only a sample function for demonstration purposes.
/// </remarks>
function DoSomething: String;

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

Подсказка: нажмите либо Ctrl+Shift+D, либо Ctrl+Alt+D (я видел оба на разных ПК), и откроется окно, чтобы упростить задачу. Я наткнулся на это, когда нажимал Ctrl+Shift+S для сохранения, но случайно нажал D.

Я хотел бы знать, как я могу экспортировать эту документацию в файл справки CHM? Я хотел бы сделать файл справки, связанный с моей библиотекой, чтобы разработчик мог использовать F1 в коде и видеть объяснение того, что делает код. Так же, как стандартная исходная документация Delphi (и большинство других языков).


person Jerry Dodge    schedule 09.06.2012    source источник
comment
Моим первым побуждением было порекомендовать Microsoft SandCastle, но, посмотрев дальше, я не думаю, что именно то, что вы ищете, уже доступно. Но есть хорошая альтернатива под названием SynProject, как описано в этой теме: stackoverflow.com/questions/236047/   -  person Nickoli Roussakov    schedule 10.06.2012
comment
Используют ли какие-либо из этих других решений в дубликате явно XML-документацию, которую я демонстрирую в своем вопросе? Или они требуют совершенно других средств создания документации?   -  person Jerry Dodge    schedule 10.06.2012
comment
Я хочу сказать, что, как указано в вопросе, у меня уже есть большая часть моего источника, задокументированного с использованием этого формата, что кажется в некотором роде стандартом в XE2 (поскольку наведение курсора на символы показывает эту информацию). Мне нужно иметь возможность использовать то, что уже есть, и оставить этот единственный источник как единственный источник. Трудно вести одну и ту же документацию в двух разных местах.   -  person Jerry Dodge    schedule 10.06.2012
comment
Просто в качестве информации: файл справки .CHM на самом деле называется HTML Help File, а комментарии исходной документации - XMLDoc или XML documentation.   -  person Ken White    schedule 10.06.2012
comment
Они сканируют ваш код и используют комментарии для создания отправной точки. Я только что вспомнил еще одну коммерческую вещь, которую стоит попробовать: doc-o-matic.com/features. html -- думаю, это именно то, что вам нужно.   -  person Warren P    schedule 10.06.2012
comment
@WarrenP Если то, что я объяснил выше, называется XMLDoc и если doc-o-matic поддерживает XMLDoc, то это было бы идеальным решением: D   -  person Jerry Dodge    schedule 10.06.2012
comment
Окно, на которое вы наткнулись, нажав Ctrl+Shift+D, — это подключаемый модуль DevJet Documentation Insight, который теперь входит в состав Delphi. Пока ничего не доступно, но посмотрите на второй комментарий на этой странице, и Пол из DevJet говорит: они работают над инструментом для создания внешней документации в нескольких форматах непосредственно из исходного кода. Кроме того, поскольку вы большой пользователь документации исходного кода, я рекомендую вам купить обновление v2 для вашего плагина Documentation Insight.   -  person LachlanG    schedule 10.06.2012
comment
@WarrenP, вы упомянули, что Help & Manual поддерживает документацию по исходному коду и может сканировать исходный код и извлекать комментарии? Это правильно? все еще правда?   -  person Masood    schedule 02.11.2015
comment
Я думаю, что это уже не так. Удалил мои предыдущие комментарии, так как в документации H&M больше нет упоминаний об этом. Вместо этого проверьте doc-o-matic.com или synopse.info/fossil/wiki?name=SynProject   -  person Warren P    schedule 02.11.2015


Ответы (1)


Это не файл CHM, но если вы используете Delphi Enterprise или более позднюю версию, в среде IDE есть возможность создания документации используя правильно отформатированные комментарии к исходному коду.

person LachlanG    schedule 10.06.2012
comment
Вы имеете в виду функцию создания документации (часть функций моделирования), на которую я ссылался в своем ответе @KenWhite? Если это так, то, согласно матрице функций XE2, это только Enterprise и выше (хотя у меня нет доступа к Pro, чтобы подтвердить это). Если это еще одна функция, о которой вы говорите, не могли бы вы дать ссылку на нее, так как мне интересно взглянуть. Спасибо. - person LachlanG; 11.06.2012
comment
Вообще-то, нет. (Я рад, что не проголосовал против. ‹g›) Предоставленная вами ссылка на самом деле является функциональностью, я никогда не знал о существовании. Я до сих пор не уверен, что именно это ищет Джерри (похоже, вопрос касается прямого преобразования комментариев XMLDoc в HTML, и я думал, что ваш ответ относится к поддержке XMLDoc), но спасибо за информацию. Мне нравится узнавать то, чего я не знал. :-) - person Ken White; 11.06.2012