Delphi - сбориник статей

       

XML Documentation


Для компилятора Delphi for .NET эта возможность существует с версии Delphi 8. Теперь эта возможность доступна и в компиляторе для Win32. Компилятор умеет различать в исходном тексте специальным образом оформленные комментарии и генерировать на их основе XML файлы. Формат комментариев во многом похож на XML. Каждый комментарий, который будет анализироваться на наличие тегов XML документации предшествовует документируемому объекту и должен начинаться с комбинации из трёх символов "/". Существует набор тегов, которые рекомендуется применять при оформлении комментариев. Он описан в справке .NET SDK. К сожалению для тех, кто не любит писать всякие теги руками, IDE никак не облегчает оформление таких комментариев.

Примитивный пример оформления документации:

type ///<summary> Test comment ///</summary> TForm3 = class(TForm) private { Private declarations } ///<summary> Test comment 1 ///</summary> procedure Test; public { Public declarations } end;

Примерный вид XML документации, генерируемой компилятором:

<?xml version="1.0" encoding="utf-8"?> <namespace name="Unit3"> <class name="TForm3"> <devnotes> <summary> Test comment </summary> </devnotes> <ancestor name="TForm" namespace="Forms"> <methodref name="ArrangeIcons" visibility="public" /> <methodref name="Cascade" visibility="public" /> здесь перечисляются предки и все их члены </ancestor> <members> <procedure name="Test" visibility="private"> <devnotes> <summary> Test comment 1 </summary> </devnotes> </procedure> </members> </class> <variable name="Form3" type="TForm3" /> </namespace>



Содержание раздела