13.2.10. Sekcja komentarza ogólnego

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... */
                

13.2.10.1. Podsekcja jednoparagrafowa

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 */
                    

13.2.10.2. Podsekcja listingu

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

13.2.10.3. Podsekcja warunkowa

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

13.2.10.4. Kopiowanie nazw z tablicy parametrów wyświetlanych

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łym
		    
opis 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.