|
:: MVP ::
|
|
|
:: RSS ::
|
|
|
Замечательная это вещь – XML комментарии. С их интеграцией (начиная с Delphi 2005) мы получили новый,
более мощный, тип подсказок – Help Insight.
Рассмотрим пример:
///
///
///
///
///
///
/// boolean
function Sample( A, B: Integer; C: string = 'NULL' ): boolean;
begin
end;
|
Все просто: summary — описание метода, param — описание параметров, returns — описание возвращаемого значения,
see — ссылка на другое описание (полный список тэгов можно посмотреть в MSDN).
Также можно использовать некоторые теги из HTML (например <b> или <i>). На их основе можно генерировать
документацию как средствами самой Delphi, так и с помощью сторонних программ (например, Doc-O-Matic Express).
Комментарии можно писать в объявлениях классов, процедур, функций, типов и даже переменных.
Жаль только, что создавать эти комментарии не так удобно, как в MSVS, где достаточно написать 3 слеша (“///”) для того,
чтобы получить “полноценную” заготовку. В Delphi для создания XML комментария можно воспользоваться шаблоном — наберите
в тексте программы (перед процедурой или функцикй) summary и нажмите клавишу Tab - появится заготовка следующего вида:
Относительно примера, приведенного в начале статьи, это не очень удобно, ведь в заготовке отсутствует описание входных
параметров и возвращаемого результата. Так что дальше мы набираем в тексте param, жмем Tab, и продолжаем это до
тех пор, пока заготовка для описания не будет полной.
Если у вас установлено расширение CnPack то, напечатав в тексте 3 слеша (“///”) подряд появится список, из которого можно
выбрать нужную заготовку. Это уже удобнее, но все равно далеко от MSVS.
Решение было найдено случайно, и находится оно среди примеров к Delphi (в XE это папка Samples\Delphi\VCL\ToolsAPI\Productivity\,
если она там отсутствует - попробуйте скачать примеры с SVN).
Это пример эксперта, который делает создание XML комментариев таким же простым, как в MSVS. Все что нужно – просто его
установить (для тех, кто "в танке", предусмотрена инструкция по установке, читайте readme.txt).
Работает этот эксперт замечательно, если вы придерживаетесь синтаксиса, принятого в Delphi, а именно – не ставите пробелов между
скобками и параметрами (см. первый пример). Если вы, как и я, любите ставить эти пробелы, то нужно внести в код небольшие изменения:
////////////////////
//
// CPPParserImpl.pas
//
////////////////////
// Оригинал
function ParseCPPDeclaration(const Declaration: string): string;
var
RoutineDeclaration: TRoutineDeclaration;
begin
RoutineDeclaration := ParseCPP(Declaration);
Result := RoutineDeclaration.XML;
RoutineDeclaration.Free;
end;
// Нужно сделать так
function ParseCPPDeclaration(const Declaration: string): string;
var
RoutineDeclaration: TRoutineDeclaration;
S: string;
begin
S := StringReplace(Declaration, ' ', '', [rfReplaceAll]);
RoutineDeclaration := ParseCPP(S);
Result := RoutineDeclaration.XML;
RoutineDeclaration.Free;
end;
///////////////////////
//
// DelphiParserImpl.pas
//
///////////////////////
// Оригинал
function ParseDelphiDeclaration(const Declaration: string): string;
var
RoutineDeclaration: TRoutineDeclaration;
begin
RoutineDeclaration := Parse(Declaration);
Result := RoutineDeclaration.XML;
RoutineDeclaration.Free;
end;
// Нужно сделать так
function ParseDelphiDeclaration(const Declaration: string): string;
var
RoutineDeclaration: TRoutineDeclaration;
S: string;
begin
S := StringReplace(Declaration, ' ', '', [rfReplaceAll]);
RoutineDeclaration := Parse(S);
Result := RoutineDeclaration.XML;
RoutineDeclaration.Free;
end;
|
Если будете ставить эксперт, прилагающийся к этой заметке, то никаких изменений вносить не нужно (все уже паправлено за вас:)).
Хочется надеяться, что в следующих версиях Delphi это станет штатной возможностью!
.: Пример к данной заметке :.
|
|
При использовании материала - ссылка на сайт обязательна
|
|
