XML dokumentace a Help Insight

vložil Radek Červinka 9. června 2010 01:19

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.

HelpInsight

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

    1TTestClass = class
    2  public
    3/// <summary>
    4/// Hlavní spouštěcí metoda
    5/// </summary>
    6/// <param name="sFileName">jméno souboru</param>
    7/// <param name="iRights">práva</param>
    8    procedure Execute(const sFileName:string; iRights:Integer);
    9  end;
   10{ TTestClass }
   11
   12procedure TTestClass.Execute(const sFileName: string; iRights: Integer);
   13begin
   14  writeln(sFileName);
   15end;
   16
   17var
   18  oTestClass: TTestClass;
   19begin
   20  oTestClass := TTestClass.Create;
   21  try
   22    oTestClass.Execute('file.txt', 10);
   23  finally
   24    oTestClass.Free;
   25  end;
   26end.

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:

HelpInsight

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é:

Delphi XML options

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.


Nabízíme Delphi školení a konzultace na různá témata, primárně ve Vaší firmě.

Tagy: ,

Praxe

Komentáře

11.8.2013 11:43:22 #

TLama

Ne všechny edice Delphi psaní XML komentářů podporují. CnWizards, z jejichž Input Helperu je screenshot v článku tuto podporu supluje i pro nižší edice (lze nadefinovat i vlastní šablony v symbol listu Code Comments in XML Style).

TLama

Komentování ukončeno

Naše nabídka

Partial English version.

MVP
Ing. Radek Červinka - Embarcadero MVP
profil na linkedin, Twitter:@delphicz

Nabízím placené poradenství a konzultace v oblasti programování a vývoje SW.
Dále nabízíme i vývoj speciálního software na zakázku.

Neváhejte nás kontaktovat (i ohledně reklamy nebo burzy práce).

Pokud chcete podpořit tento server libovolnou částkou, můžete použít PayPal. Moc děkuji.

Delphi Certified Developer

O Delphi.cz

Delphi je jediný moderní RAD nástroj podporující tvorbu nativních aplikací pro platformu Win32, Win64 , Mac OSX a na iPhone a Android (s výhledem na další platformy díky FireMonkey) na současném trhu (včetně Windows 8.1).

V současnosti je světová komunita přes dva miliónů vývojářů.

Delphi.cz je nezávislý portál pro uživatele Delphi. Portál není koncipován pro úplné začátečníky, i když i ti se zde nebudou nudit, ale spíše na programátory, kteří již něco znají a chtějí své znalosti dále rozvíjet a sledovat novinky.

Anketa

Poslední komentáře

Comment RSS