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świetlanejnumer 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 |