1 IDE
2 Angular (compodoc)
- 2.1 compodoc
  - 2.1.1 JSDoc tags
    - 2.1.1.1 @return / @returns
    - 2.1.1.2 @param
    - 2.1.1.3 @ignore
    - 2.1.1.4 @link
  - 2.1.2 odkazy

IDE

Webstorm aj IntelliJ IDEA používajú na dokumentáciu rovnaké klávesové skratky:

Dokumentácia sa zobrazuje pomocou Ctrl + Q
Nápoveda pre argumenty funkcií pomocou Ctrl + P

Angular (compodoc)

Na dokumentáciu frontendu používame nástroj compodoc. Ten analyzuje zdrojové kódy a na základe JSDoc anotácií (obdoba Javadoc pre Javascript) generuje dokumentáciu všetkých súčastí angular projektu - modulov, komponentov, injectables (servís) atď.

Pokiaľ chceme vygenerovať dokumentáciu je najprv nutné mať vygenerovaný test coverage pre projekt, keďže ho compodoc zahŕňa do generovanej dokumentácie. Na vygenerovanie coverage treba spustiť nae:full-test skript z package.json súboru v koreňovom priečinku workspace-u. Dokumentácia sa potom generuje nae:doc skriptom z toho istého súboru.

Vygenerovanú dokumentáciu si je možné prezerať vo webovom prehliadači. Stačí otvoriť index.html súbor, ktorý sa nachádza vo vygenerovanom priečinku docs/compodoc/.

compodoc

Podľa compodoc dokumentácie pracuje compodoc s JSDoc komentármi. To nie je tak úplne pravda, keďže do tých sa píšu aj informácie o typoch, compodoc je však schopný extrahovať tieto informácie aj bez toho, aby museli byť uvádzané v komentároch.

Komentáre s dokumentáciou musia byť v tvare /** */ (ako Javadoc). Pokiaľ chceme, aby bol vygenerovaný text v dvoch riadkoch, je nutné jeden riadok v komentári vynechať.

/**
 * Riadok 1
 * Riadok 2
 */
public foo() {}

/**
 * Riadok 1
 *
 * Riadok 2
 */
public bar() {}

Keď chceme mať blok kódu, musíme mať od hviezdičky 4 medzery. Ak chceme formátovať pridávame od hviezdičky 4 + počet ktorý chceme mať v bloku.

V komentári je možné používať ` na ohraničenie inline kódu.

/**
 * Text `foo();` text
 */
public foo() {}

Pokiaľ chceme napísať komentár ku triede pred ktorou stojí anotácia (napríklad pre komponent), tak sa komentár s dokumentáciou píše pred túto anotáciu.

/**
 * dokumentacia
 */
@Component({
  selector: 'foo',
  templateUrl: './foo.component.html',
  styleUrls: ['./foo.component.scss']
})
export class FooComponent {}

V dokumentácii je možné používať markdown syntax na formátovanie textu. IDE taktiež podporuje markdown v zobrazenej nápovede k dokumentácii. Treba však mať na pamäti, že Clean code neodporúča formátovať dokumentáciu priamo v kóde, ale prenechať formátovanie na nástorje, ktoré ju extrahujú (compodoc).

JSDoc tags

compodoc podporuje len obmedzené množstvo dokumentačných tagov.

@return / @returns

Je jedno ktorú formu anotácie používate, obe robia to isté a obe sa vo výslednej dokumentácii zobrazujú ako Returns (možno si všimnúť aj na obrázku).

/**
 * @return always returns 1
 */
public foo(): number {
  return 1;
}

@param

Dokumentuje jeden vstupný argument. Typ argumentu sa neuvádza - compodoc ho dokáže extrahovať sám.

/**
 * @param arg - the value that
 * should be returned
 * @return the input argument
 */
public foo(arg: number): number {
    return arg;
}

@ignore

Symbol ktorého dokumentačný komentár obsahuje tento tag bude z dokumentácie úplne vypustený. Avšak dokumentácia k nemu sa stále v IDE zobrazí, čiže je ho možné použiť napríklad pri dokumentácii pre interné funkcie schematikov (ktoré compodoc do dokumentácie defaultne zahŕňa).

@link

Vytvorí hyperlinku na inú časť dokumentácie/externú adresu. Linka sa odkazuje na triedu. Pokiaľ chceme odkázať na atribút triedy je potrebného uviesť za #. Pokiaľ sa chceme odkázať na internetovú stránku, jednoducho uvedieme jej URL miesto názvu triedy.

Do hranatých zátvoriek môžeme uviesť text, ktorý má plniť úlohu linky. Hranaté zátvorky je možné vypusťiť, potom má linka podobu názvu triedy na ktorú sa odkazujeme (aj keby sme sa odkazovali na jej atribút). Treba však myslieť na to, že v IDE sa v takomto prípade zobrazuje text uvedený v zložených zátvorkách aj s # symbolom.

Odkazovať sa na dokumentáciu tried pomocou ich názvu je možné iba pre triedy v rámci projektu. Pokiaľ sa chceme odkazovať na iné triedy na príklad z Angularu, či samotného typescriptu/javascriptu je potrebné použiť odkaz pomocou URL.

/**
 * For more information see [foo]{@link ConfigurationService#foo}
 * @returns the value of `foo(1)`
 */
public bar(): number {
    return this.foo(1);
}

odkazy

https://compodoc.app/guides/comments.html

https://compodoc.app/guides/jsdoc-tags.html

Netgrif Application Engine

Písanie dokumentácií

IDE