Jak vytvořit systém nápovědy ve vlastních zdrojových textech ?

V řadě případů by se hodil systém nápovědy, který obsahuje knihovna MenuLib. Nápověda se hodí při tvorbě vlastních knihoven i zdrojových textů a při jejich opakovaném používání zvláště po delší přestávce od okamžiku jejich vytvoření.

envelope Popis:

Pokud opakovaně používáme některé vlastní funkce a procedury je neocenitelným pomocníkem stručná a rychlá nápověda. Obvykle stačí stručný popis vlasrností, typu předávaných parametrů popř. typu vrácené hodnoty dotyčné procedury nebo funkce. Takto je vybavená např. knihovna MenuLib. StudioWin však umožňuje vybavit podobnou nápovědou i vlastní knihovny nebo zdrojový text.

lightbulb Řešení:

Export nápovědy a seznamu funkcí ze souboru STP,LIB

StudioWin umožňuje autorovi knihoven uložit jako nedílnou součást zdrojového textu také nápovědu a popis k vybraným funkcím. Tato nápověda se pak uživateli zobrazí pokud danou knihovnu, nebo zdrojový text vloží do projektu a při psaní vlastního zdrojového textu v editoru StudioWin vyvolá dialog klávesou F5.

Tvorba nápovědy

Nápověda se generuje na základě klíčových slov umístěných v zdrojovém textu. Tato klíčová slova a text vlastní nápovědy musí být pro vlastní překladač komentářem. To znamená že buď budou uvozena středníkem nebo umístěna v blokovém komentáři.

Struktura nápovědy:

1. $EXPORT [nepovinný vkládaný text]

  • $EXPORT  uvozuje celý blok exportované funkce do seznamu, tj. nápovědu a vlastní deklaraci funkce. Po tomto slově se očekává nepovinná nápověda a povinná deklarace funkce nebo rutiny.
  • Vkládaný text: pokud se za slovem $EXPORT: nachází libovolný text, je to chápáno jako požadavek autora na vypnutí mechanismu rozebrání deklarace funkce a sestavení jména pro vložení do textu. Tzn. že pokud uživatel vybere ze seznamu danou funkci bude do jeho zdrojového textu vložen právě tento text a nikoliv jméno funkce vzniklé rozborem deklarace funkce.

2. $HELP> <$HELP

  • $HELP> uvození začátek textu, který je chápán jako nápověda
  • <$HELP ukončení textu nápovědy

3. deklarace funkce nebo subroutiny

  • součástí nápovědy je také vlastní deklarace funkce, která již je součástí kódu knihovny a musí následovat za řádkem nápovědou nebo za slovem $EXPORT

Příklad 1: Zařazení funkce do seznamu i s nápovědou

/*
$EXPORT
$HELP>
Vytvoření položky menu typu ŘÁDEK
Předávané parametry:
1. Parametr: text položky
Výstupní hodnota:
0-zákaz zobrazení 1-zobrazení povoleno
<$HELP
*/

function byte MeLine(const string txt)
/* zde je vlastni kod knihovny
...
*/

return

Výsledkem je tato nápověda:

faq_help_export_o1Příklad2: Zařazení funkce do seznamu bez nápovědy

; $EXPORT
subroutine MeEnd()
begin
/*kod rutiny*/
end

Použití nápovědy

Nápověda se v editoru StudioWin vyvolá klávesou F5 nebo z místní nabídky editoru. V zobrazeném okně je seznam funkcí a rutin. Funkce mají ikonu červenou a s identifikací předávaného typu. Rutiny mají ikonu modrou a se slovemSUB. V seznamu je možné se pohybovat šipkami nahoru a dolů nebo myší. Při přechodu kurzoru myši přes položku seznamu se zobrazí nápověda která obsahuje plnou deklaraci funkce a pod linkou je komentář (ten který je ohraničen slovy $HELP> komentář <$HELP). Pokud je některá položka vybrána a stisknuta klávesa ENTER, dojde ke vložení jména funkce a jejích parametrů, ale bez typů, do místa volání. Pokud v deklaraci nápovědy bylo za slovem $EXPORT nalezen text, je tento text vložen místo jména funkce.

Soubor ke stažení: Systém nápovědy pro uživatelský kód