Więcej o firmie ELESOFTROM

Firma ELESOFTROM specjalizuje się w wykonywaniu i naprawianiu oprogramowania dla sterowników mikroprocesorowych.

Posiadamy ponad 10-letnie doświadczenie w tej dziedzinie.

W realizowanych projektach stawiamy na niezawodność i wydajność programów.

Naprawa oprogramowania

Oprogramowanie na zamówienie


Strona główna

Pełna oferta

Doświadczenie

O firmie

Kontakt


DioneOS - RTOS dla urządzeń embedded

Firma ELESOFTROM opracowała system RTOS dla procesorów ARM Cortex-M3 oraz msp430.

System jest zoptymalizowany pod względem wydajności, dzięki czemu uzyskano krótki czas przełączania pomiędzy wątkami.
System dostarcza elementy (np. semafory, mutexy, timery, kolejki itp.) niezbędne do tworzenia wielowątkowego firmware'u.

Wersja dla Cortexa została całkowicie przetestowana przy pomocy środowiska do automatycznego testowania.

Przeczytaj więcej:

Strona o systemie DioneOS

Niezawodność

Wydajność

Dokumentacja DioneOSa

Prezentacje n.t. DioneOS


^ Blog index    << Jak zbudować własny firmware    >> Jak zainstalować i skalibrować PenMount TouchScreen na IVI Tizen Linux

Dokumentowanie kodu źródłowego

2012-05-12    dr inż. Piotr Romaniuk

Spis treści

Wstęp
Doxygen - narzędzie do tworzenia dokumentacji,
Składnia opisów w kodzie źródłowym właściwa dla Doxygena,
Konfiguracja opcji generowania dokumentacji (doxywizard).
Dopasowanie wyglądu dokumentacji
Linki (dokumentacja Doxygena)

Wstęp
Nawet dobry kod źródłowy bez dokumentacji dla programisty staje się trudny do utrzymywania. Brak lub fragmentaryczność dokumentacji staje się dokuczliwa, gdy inni członkowie zespołu próbują wykorzystać lub zmieniać istniejący kod. W efekcie wymaga to od nich dodatkowego nakładu pracy niezbędnego do zrozumienia jak one działają i jak należy ich używać. Okazuje się, że problem ten dotyczy również autora kodu, ponieważ po upływie jakiegoś czasu (np. kilku miesięcy) zapomina on szczegóły własnej implementacji. Z powyższego powodu najlepszym momentem do sporządzenia dokumentacji jest czas po wprowadzeniu zmian, czy w trakcie tworzenia implementacji. Oczywiście trudno wymagać aby programiści pisali kod i jednocześnie tworzyli (aktualizowali) jego dokumentację w odrębnych plikach opisowych (.doc, .pdf, itp.), będąc przy tym zmuszonym do korzystania z różnych programów.
Ponieważ problem ten jest dość powszechny powstały narzędzia wspomagające tworzenie dokumentacji na podstawie informacji dostarczonych w plikach źródłowych. Dzięki temu, już w trakcie modyfikacji źródeł, w tym samym edytorze, programista może zawrzeć opis, na podstawie którego będzie zbudowana dokumentacja. W kolejnym kroku, po uruchomieniu odpowiednio skonfigurowanego narzędzia, wydziela ono i porządkuje opisy generując zestaw plików, np. w formacie HTML czy LaTeX.

Doxygen - narzędzie do tworzenia dokumentacji
Dobrym przykładem narzędzia do budowania dokumentacji z plików źródłowych może być
Doxygen. Informacja przeznaczona do dokumentacji umieszczana jest w blokach komentarza, dzięki czemu nie wpływa na proces kompilacji. W dalszej częsci tego opisu skupiam się na wykorzystaniu Doxygena do dokumentacji źródeł napisanych w języku C, chociaż Doxygen radzi sobie on też z innymi językami, takimi jak: C++, C#, Java, PHP, Fortran, VHDL. W przypadku języka C komentarze są usuwane przez preprocesor języka C przed kompilacją.
Przykładowo, implementacja pewnej funkcji może być opisana w kodzie nastepująco:

/** @brief Waits on the semaphore with timeout
*
* Calling this may cause context switch.
* @warning Do not call it when preemption is disabled - it will not block or throw os_bug
* @note may throw os_bug if os_ready_threads is empty, or when semaphore counter overflows \n
* Timeout may be shorter than specified in argument list by 1 unit or longer, depending on latencies in the system.
*
* @param[in] sem the pointer to the semaphore structure
* @param[in] timeout waiting timeout in os_tick units
* @return #OS_STATUS_OK when success \n
* #OS_PREEMPT_DIS when preemption is disabled and check this issue is disabled in config.h \n
* #OS_TIMEOUT when timeout has expired, note that semaphore could be released between timeout has elapsed
* and function returned. If it is important, in this case call os_sema_tryget(), but after you cannot
* obtain semaphore the release may happen so this looks again like uncertainty in return from the function.
*/

os_result_t os_sema_wait_timeouted( os_sema_t * sem, unsigned short timeout );

Co prowadzi do powstania nastepującego fragmentu dokumentacji:


Przykładowy wygląd dokumentacji wygenerowanej na podstawie opisu w kodzie źródłowym
(z dokumentacji systemu DioneOS).

Jak widać, minimalistyczny opis w pliku źródłowym, ale zawierający wszystkie niezbędne informacje, został przekształcony w wygodną do czytania formę, w formacie zestawu stron HTML, które można przeglądać przeglądarką internetową. Oprócz zapisanej treści, utworzone zostały linki do wybranych elementów (np. definicji OS_STATUS_OK, definicji typu os_sema_t). Ponadto, Doxygen tworzy spisy i indeksy alfabetyczne: plików źródłowych, struktur danych, typów danych, makrodefinicji itp. Interfejs dokumentacji pozwala na wyszukiwanie po nazwach (pole search w górnym prawym rogu). Można dodać też uzupełniające strony w HTMLu zawierające własny opis ogólny (zgrupowane w Related Pages).


Widok całego okna dokumentacji, aby zobaczyć jak się zachowuje przykładowa dokumencja kliknij na obrazku albo tutaj.
Zwróć uwagę na dodane linki do innych stron (strona systemu DioneOS oraz główna strona firmy ELESOFTROM)
umieszczone na górze oraz dole strony, stworzone przez własny nagłówek i stopkę w HTMLu (header & footer).

Składnia opisów w kodzie źródłowym własciwa dla Doxygena

Fragmenty przeznaczone dla Doxygena rozpoczynają się sekwencją '/**' i kończą '*/', dzięki temu są one wykrywane przez preprocesor języka C jako komentarz i pomijane w procesie kompilacji źródeł a z kolei łatwo wydzielane przez samego Doxygena.
Słowa kluczowe Doxygena są poprzedzone znakiem @, a odwołania do innych udokumentowanych elementów kodu poprzedza się znakiem #. Poniżej przedstawiona jest składnia z przykładami niezbędna do opisania podstawowych elementów w plikach źródłowych.

Opis plików źródłowych

@file - określenie nazwy pliku,
@anchor - nazwa 'zakotwiczenia', do którego można się odwoływać z innych miejsc tworząc linki,
@brief - skrócony opis treści zawartej w pliku,
@author - autor pliku,
@version - wersja pliku.

Przykład

/** @file semaphore.h
* @anchor sema
* @brief Semaphores
*
* @author Piotr Romaniuk, (c) ELESOFTROM
* @version 1.0 Feb 4, 2011
*
* A semaphore is one of synchronization object, it provides well-known mechanism for signalling
* between threads. The semaphore contains an internal counter initialized with a number
...
*/

Opis funkcji

Opis funkcji powinien znaleźć się przed definicją/deklaracją funkcji i zawierać następujące elementy:

@brief - skrócony opis funkcji (aż do pustej linii),
    dalszy opis jest traktowany jako opis rozszerzony.
@param[ in | out | in/out ] - wyliczenie parametrów funkcji (Uwaga: pomiędzy nazwą a znaczeniem nie należy umieszczać znaku myślnika),
    w nawiasie kwadratowym podaje się odpowiednio czy jest to parametr wejściowy, wynikowy, czy jest używany jako wejście i wyjście.
@return - opis zwracanej wartości przez funkcję.

Przykład

/** @brief Try to obtain semaphore
*
* The function tries to obtain semaphore but never blocks (waits) on it.
* The result of operation is returned by return code.
* @param[in] sem pointer to the semaphore structure
* @return #OS_STATUS_OK when semaphore has been obtained\n
* #OS_WOULD_WAIT if semaphore is busy and trial of waiting on it would block
*/

os_result_t os_sema_tryget( os_sema_t * sem );

W przykładzie widoczne jest odwołanie do dwóch kodów opisanych gdzie indziej: OS_STATUS_OK oraz OS_WOULD_WAIT, prawidłowa składnia linku wymaga użycia znaku # podczas odwoływania się.

Opis struktury

Ogólny opis struktury powinien znaleźć się przed jej deklaracją, natomiast opis pól można umieścić jako kontynuację linii, w których się znajdują (zwróć uwagę na sekwencję znaków /**<, w szczególności na znak mniejszości) .

@brief - skrócony opis struktury/pola,
Przykład:

/**@brief data type for state machine description */

struct os_state_machine_s{

os_list1_t list_chain;

/**<brief field for chaining in state machine manager on active state machines list*/

os_sm_handler_t *handlers;

/**<brief table of pointers to functions that handle events (handlers) in each state*/

int state;

/**<@brief current state */

int states_nb;

/**<@brief number of states*/

os_ring_buffer_ev_t ev_queue;

/**<@brief queue that stores incomming events */

void * xdata;

/**<@brief extra data for user */

};

Opis makrodefinicji

W zależności od rozdzaju makrodefinicji, jej opis może ją poprzedzać lub występować w linii definicji.

Przykład 1.

define OS_WAIT_INFINITE 0 /**<@brief symbol for infinite wait on semaphore */

Przykład 2.

/** @brief Macro releases the semaphore.
*
* @note Use it only in ISR.\n
* @note may throw os_bug if semaphore counter overflows.
* @param[in] sem the pointer to the semaphore structure
* @return always returns #OS_STATUS_OK
*/

#define os_sema_post_intr( sem ) os_sema_post_common( sem , 1 )

Opis definicji typu wyliczanego (enum)

Przykład

/** @brief Thread state.
*
* The values for thread state description.
*/
enum os_thread_state_e{
OS_THREAD_WAIT = 1, /**<@brief Thread is waiting on some waiting object. It cannot be scheduled */
OS_THREAD_READY = 2,/**<@brief Thread is ready to be scheduled, but now higher priority thread is running */
OS_THREAD_RUNNING = 3/**<@brief Thread is running, its context is current */
};

Inne słowa kluczowe

@anchor - definiuje 'zakotwiczenie', do którego można się odwołać w opisach poprzez poprzedzenie nazwy znakiem #.
@warning - wyróżnione ostrzeżenie w dokumentacji,
@note - wyróżniona notka w dokumentacji,
@todo - wyróżniony opis wymagający wykonania (niedokończony, niezrealizowany),
@bug - wyróżniony opis błędu (nierozwiązanego),
@deprecated - oznaczanie elementów przestarzałych, które będą usunięte w kolejnych wersjach kodu.
Doxygen może utworzyć osobną stronę z listą błędów, ostrzeżeń, notatek i elementów do zrobienia oznaczonych powyższymi dyrektywami w kodzie źródłowym.
@code / @endcode - definiuje sekcję w opisie formatowaną jako kod źródłowy,
W opisach komentarza Doxygena można umieszczać składnię w formacie HTML, np. <br>, <b> </b>,
a także wstawiać obrazki, jak w HTMLu, poprzez <img src="nazwa-pliku">
@addtogroup / @{ / @} / @defgroup - definiowanie grup (odpowiadają znaczeniowo modułom złożonym z wielu plików źródlowych),
@mainpage / @page / @subpage - tworzenie oddzielnych stron włączanych potem do spisu treści w dokumentacji.

Konfiguracja opcji generowania dokumentacji (doxywizard)

Wygodnym interfejsem do konfiguracji opcji generowanej dokumentacji jest Doxywizard. Pozwala on na wskazanie położenia plików źródłowych, z których będzie generowana dokumentacja, katalogu wynikowego oraz wielu opcji określających poziom szczegółowości i wygląd dokumentacji. W szczególności możliwe jest zdefiniowanie symboli preprocesora, które będa interpretowane podczas tworzenia dokumentacji, co pozwala na warunkowe włączanie fragmentów, które będą widoczne tylko podczas kompilacji a ukrywane w dokumentacji.


Wygląd interfejsu do konfiguracji opcji Doxygena, w lewym dolnym panelu
widoczny jest aktywny help kontekstowy (po najechaniu myszką na opcję konfiguracji,
wyświetlany jest odpowiedni tekst pomocy, wyjaśniajacy znaczenie opcji)

Doxygen umożliwia również włączenie do dokumentacji kodu źródłowego uzupełnionego o aktywne linki do opisów zdefiniowanych elementów.


Przykładowy fragment dokumentacji z kodem źródłowym,
linie z wyróżnionym numerem na niebiesko (np. 00017, 00024)
są linkami prowadzącymi do opisów zdefiniowanych elementów.

Dopasowanie wyglądu dokumentacji

Doxygen pozwala na dopasowanie wyglądu dokumentacji, jest to możliwe poprzez określenie następujących elementów:

  • plik loga,
  • kolorystyka interfejsu,
  • układ dokumentacji (forma pojedynczego pliku HTML albo układ oparty na ramkach)
  • elementy dokumentacji (obecność funkcji do przeszukiwania, indeksu, spisów itp.),
  • wskazanie własnego nagłówka i stopki w HTML, które będą odpowiednim fragmentem plików dokumentacji w HTMLu (zostaną one włączone na początku i końcu tworzonych plików - stanowiąc niejako ich opakowanie),
  • własny zestaw stylów CSS - możliwość wpływania na kolorystykę, czcionki, itp.

Można również za pomocą zestawu prostych skryptów rozszerzyć proces budowania dokumentacji, zamieniając utworzone pliki w pliki PHP w celu uzyskania dodatkowych funkcji (np. ochrony dostępu do dokumentacji poprzez logowanie i rejestrację użytkowników, albo włączenie innych elementów tworzonych dynamicznie).

Linki

Dokumentacja on-line Doxygena (po zainstalowaniu Doxygena będzie też dostępna lokalnie)
Lista słów kluczowych, występujących jako dyrektywy Doxygena