Už několik verzí Delphi podporuje XML dokumentaci přímo v kódu (dříve bylo vhodné pro dokumentaci použít PasDoc - což se samozřejmě nevylučuje).
IDE zároveň takové komentáře přímo v kódu zobrazuje jako hint při zastavení nad identifikátorem (tomu se říká HelpInsight).
Pokud chceme použít tento způsob komentování, napíšeme /// a stiskneme CTRL+mezerník, čímž dostaneme nápovědu podporovaných elementů, nebo přímo napíšeme /// a název elementu, tj. např. ///param a stiskneme uvedenou klávesovou zkratku, čímž se vygeneruje patřičná poznámka.
Nejdůležitější je summary, které je zobrazováno jako první řádek, param popisuje jeden parametr (atribut name je generován Delphi), viz screenshot dole. Mimochodem mají tyto komentáře umět i vyhodnotit výraz z kódu, který je znám v okamžiku příchodu na řádek komentáře, ale nikdy jsem to nepoužil.
Pokud se Vám tento způsob psaní XML dokumentace zdá pomalý, můžete se inspirovat Live Template co napsal Pawel Glowacki a patřičně si těch několik řádků upravit, aby to vyhovovalo právě Vám.
Mějme nějaký podobný zdrojový kód
TTestClass = class
public
/// <summary>
/// Hlavní spouštěcí metoda
/// </summary>
/// <param name="sFileName">jméno souboru</param>
/// <param name="iRights">práva</param>
procedure Execute(const sFileName:string; iRights:Integer);
end;
{ TTestClass }
procedure TTestClass.Execute(const sFileName: string; iRights: Integer);
begin
writeln(sFileName);
end;
var
oTestClass: TTestClass;
begin
oTestClass := TTestClass.Create;
try
oTestClass.Execute('file.txt', 10);
finally
oTestClass.Free;
end;
end.
Určitě vidíte, že jsem doplnil komentář pro metodu Execute. Nyní při zastavení (alternativně Shift+Ctrl+H nebo menu View - Help insight) na řádku s oTestClass.Execute se zobrazí Help Insight s naším textem:
Help Insight funguje i bez kompilace, jen musí být patřičná jednotka k nalezení.
Mimochodem, pro formátování se používá soubor "c:\Program Files\Embarcadero\RAD Studio\7.0\ObjRepos\en\HelpInsight.xsl" - to jen kdyby byl zájem si ho upravit.
Kompilátor umí také z poznámek generovat XML soubory, formát je podobný jako od Visual Studia, což by kromě jiného mělo znamenat, že můžete použít nástroje pro jejich zpracování.
Delphi samotné by mělo být schopno generovat dokumentaci, někde přes modelování - nejsem si jist, jelikož modelování nemám nainstalované
(resp. jsem si přesunul všechny soubory Borland.Together*.DLL do zálohy, tj. jsem přišel o modelování).
Nastavení kompilátoru pro generování XML je jednoduché:
Výsledné XML můžete prohnat nějakým nástrojem nebo za pomoci patřičného souboru XSL transformovat. Každopádně si myslím, že nejméně Help Insight je vhodné používat.
RSS