| SZARP PLC HOWTO | ||
|---|---|---|
| Poprzedni | Rozdział 13. Automatycznie generowana dokumentacja do programów technologicznych przy użyciu skryptu docgen | Następny |
W sekcji ogólnej mogą być umieszczane komentarze do funkcji, zmiennych, struktur, itp. kodu źródłowego programu technologicznego, a także opis jego działania, użytych algorytmów czy ogólna instrukcja użytkowania danego sterownika. Sekcje ogólne mogą występować w kodzie źródłowym w dowolnym miejscu i w dowolnej ilości. W pliku wyjściowym umieszczane są przed wszystkimi innymi komentarzami pozostałych sekcji w kolejności występowania w pliku źródłowym.
Początek sekcji ogólnej wyznacza ciąg znaków:
/*!komentarz - start */
Koniec sekcji ogólnej wyznacza ciąg znaków:
/*!komentarz - stop */
Komentarze umieszczone między tymi ciągami znaków zostaną odczytane i umieszczone w pliku wynikowym. Prawidłowy format komentarzy to:
/* ...tekst... */
Każdy akapit komentarza musi musi występować pojedynczo w jednej linii, na przykład:
/*!komentarz - start */
/*
...pierwszy akapit tekstu komentarza...
...drugi akapit tekstu komentarza...
*/
/*!komentarz - stop */
Istnieje również krótszy sposób wyznaczania sekcji ogólnej:
/*!*/
/*...tekst komentarza... */
Istnieje możliwość połączenia wielu linii komentarza w jeden akapit (paragraf) - przydatna, jeśli wstawianie nowego paragrafu po końcu każdej linii psułoby znacząco wygląd dokumentacji. W tym celu należy w sekcji ogólnej stworzyć podsekcję jednoparagrafową, którą rozpoczyna ciąg znaków:
<!-- komentarz - 1p - start -->
Koniec podsekcji jednoparagrafowej wyznacza ciąg znaków:
<!-- komentarz - 1p - stop -->
Tekst komentarza zawarty między tymi ciągami znaków zostanie wstawiony do pliku wynikowego jako jeden akapit, choć z podziałem linii, na przykład:
/*!komentarz - start */
/*
...pierwszy akapit tekstu komentarza...
<!-- komentarz - 1p - start -->
...pierwsza linia drugiego akapitu tekstu komentarza...
...druga linia drugiego akapitu komentarza...
<!-- komentarz - 1p - stop -->
...trzeci akapit tekstu komentarza...
*/
/*!komentarz - stop */
W dokumentacji do programów technologicznych sterowników zdarza się konieczność umieszczenia, oprócz opisów tekstowych, graficznych czy formuł matematycznych, opisu w formie pseudokodu. Specjalnie do tego zastosowania powstała podsekcja listing, dzięki której pseudokod w niej umieszczony może być wyświetlany w prawidłowy sposób (tj. czcionką o stałej szerokości i z zachowaniem źródłowego formatowania) oraz mogą zostać do dane numery poszczególnych wierszy. Początek podsekcji listingu rozpoczyna ciąg znaków:
<!-- listing - start -->
Koniec podsekcji listingu wyznacza ciąg znaków:
<!-- listing - stop -->
Istnieje możliwość warunkowego dołączania części sekcji komentarza ogólnego - w zależności od tego czy w programie źródłowym jest zdefiniowana (lub niezdefiniowana) definicja dla preprocesora języka C - przy pomocy odpowiedniego wpisu w pliku ports (patrz opis opcji opt_directiveX w Sekcja 13.2.15). W tym celu należy otoczyć warunkowy fragment komentarza odpowiednimi instrukcjami warunkowymi:
<!-- komentarz - ifdef(KOCIOL_1) --> <!-- komentarz - funkcja(85) --> - Pomiar dokonywany czujnikiem Pt100 o zakresie przetwarzania 0..200°C <!-- komentarz - endif -->lub
<!-- komentarz - ifndef(KOCIOL_1) --> <!-- komentarz - funkcja(85) --> - Pomiar dokonywany czujnikiem Pt100 o zakresie przetwarzania 0..200°C <!-- komentarz - endif -->
Zdarza się potrzeba skopiowania w dosłownym brzmieniu nazw z tablicy parametrów wyświetlanych do sekcji komentarza ogólnego (np. przy tworzeniu opisu znaczenia poszczególnych funkcji). Ułatwia to funkcja automatycznego kopiowania tych nazw w wyznaczone miejsce. Aby z niej skorzystać, w sekcji komentarza ogólnego w miejscu, w którym ma zostać dana nazwa wstawiona, musi pojawić się ciąg znaków:
<-- komentarz - wyswietlacz_staly -->Taki ciąg znaków zostanie w pliku wynikowym zastąpiony przez:
opis wartości na wyświetlaczu stałymopis wartości na wyświetlaczu stałym jest zastępowany przez wartość z kolumny opis z pierwszego rzędu tabeli parametrów wartości wyświetlanych.
<-- komentarz - funkcja(numer funkcji) -->
numer funkcji należy zastąpić
odpowiednim numerem funkcji z tablicy wartości
wyświetlanych. Taki ciąg znaków zostanie w
pliku wynikowym zastąpiony przez:
numer funkcji - opis funkcji wyświetlanej
numer funkcji jest dosłownie
przepisanym numerem z powyższego wywołania, a
opis funkcji wyświetlanej jest
zastępowany przez wartość z kolumny
opis z odpowiedniego rzędu
tabeli parametrów wartości wyświetlanych.
| Poprzedni | Spis treści | Następny |
| Sekcja wyjść przekaźnikowych | Początek rozdziału | Sekcja komentarzy dołączalnych |