docs: add project documentation

docs/dokumentacja/dokument.lol

@@ -1,2 +1,3 @@
-\contentsline {lstlisting}{\numberline {1}{\ignorespaces Przykładowy kod 001}}{3}{lstlisting.1}%
-\contentsline {lstlisting}{\numberline {2}{\ignorespaces Przykładowy kod 002}}{4}{lstlisting.2}%
+\contentsline {lstlisting}{\numberline {1}{\ignorespaces Przykład testu jednostkowego}}{15}{lstlisting.1}%
+\contentsline {lstlisting}{\numberline {2}{\ignorespaces Funkcja mergeSort}}{18}{lstlisting.2}%
+\contentsline {lstlisting}{\numberline {3}{\ignorespaces Test algorytmu na losowej tablicy}}{19}{lstlisting.3}%

docs/dokumentacja/dokument.tex

@@ -9,7 +9,7 @@
     \input{preambula_ustawienia.tex}
 
     %polecenia zdefiniowane w pakiecie strona_tytulowa.sty
-    \title{Algorytm sortowania przez scalanie (merge sort)}		%...Wpisać nazwę projektu...
+    \title{Algorytm sortowania przez scalanie \protect\\ (merge sort)}		%...Wpisać nazwę projektu...
     \author{Mateusz Basiaga}
     \authorI{}
     \authorII{}		%jeśli są dwie osoby w projekcie to zostawiamy:    \authorII{}

docs/dokumentacja/kod/example_test.cpp

@@ -0,0 +1,6 @@
+TEST(TestMergeSorter, KeepsAlreadySortedArrayIntact) {
+  std::vector<int> test_array = { 1, 2, 3, 4, 5, 7, 8, 9 };
+  MergeSorter::sortArray(test_array);
+
+  ASSERT_THAT(test_array, testing::ElementsAre(1, 2, 3, 4, 5, 7, 8, 9));
+}

docs/dokumentacja/kod/merge_sort.cpp

@@ -0,0 +1,10 @@
+void MergeSorter::mergeSort(std::vector<int>& arr, int left, int right) {
+    if (left < right) {
+        int mid = left + (right - left) / 2;
+
+        mergeSort(arr, left, mid);
+        mergeSort(arr, mid + 1, right);
+
+        merge(arr, left, mid, right);
+    }
+}

docs/dokumentacja/kod/merge_sort_random_test.cpp

@@ -0,0 +1,13 @@
+TEST(TestMergeSorter, SortsLargeArrayWithNegativeAndPositiveDuplicates) {
+  std::vector<int> test_array;
+
+  for (int i = 0; i < 500; ++i) {
+    test_array.push_back(RandomNumberGenerator::getRandomNumber(-99, 99));
+  }
+
+  MergeSorter::sortArray(test_array);
+
+  for (std::vector<int>::size_type i = 0; i < test_array.size() - 1; ++i) {
+    ASSERT_LE(test_array[i], test_array[i + 1]);
+  }
+}

docs/dokumentacja/preambula_ustawienia.tex

@@ -101,7 +101,7 @@
 }
 
 \newcommand*{\OznaczZdjecie}[1]{
-    Rysunek \Oznacz{rys}{#1}
+    \Oznacz{rys}{#1}
 }
 
 \newcommand*{\OznaczKod}[1]{

docs/dokumentacja/tex/rozdzial1.tex

@@ -1,5 +1,37 @@
-\newpage
-\section{Ogólne określenie wymagań}		%1
-%Określenie celu pracy, co chcemy uzyskać, jakie przewidujemy wyniki
+\section{Ogólne określenie wymagań}
+\label{sec:ogolne-wymagania}
 
-\input{tex/template_tutorial.tex}
+Celem projektu jest implementacja i przetestowanie algorytmu sortowania przez scalanie (Merge Sort) w języku C++ w formie modułowego projektu.
+Projekt obejmuje nie tylko implementację samego algorytmu, ale również stworzenie dodatkowych funkcjonalności wspomagających obsługę tablic,
+a także opracowanie dokumentacji i procedur testowania.
+
+\subsection{Cel pracy}
+Głównym celem projektu jest:
+\begin{itemize}
+  \item Implementacja algorytmu sortowania przez scalanie w sposób modularny, \\ z podziałem na klasy i pliki źródłowe.
+  \item Zastosowanie dobrej praktyki programowania poprzez oddzielenie logiki aplikacji od interfejsu użytkownika.
+  \item Przeprowadzenie testów jednostkowych z wykorzystaniem frameworka Google Test w celu weryfikacji poprawności działania algorytmu w różnych scenariuszach.
+  \item Stworzenie interaktywnej aplikacji umożliwiającej użytkownikowi manipulowanie tablicami i testowanie działania algorytmu w czasie rzeczywistym.
+  \item Opracowanie szczegółowej dokumentacji projektu za pomocą narzędzi LaTeX i Doxygen.
+\end{itemize}
+
+\subsection{Zakładane wyniki}
+Oczekiwane efekty projektu to:
+\begin{itemize}
+  \item Sprawna i poprawna implementacja algorytmu Merge Sort, \\ który będzie w stanie skutecznie sortować zarówno małe, jak i bardzo duże tablice.
+  \item Zbiór testów jednostkowych pokrywających kluczowe przypadki użycia algorytmu, w tym tablice losowe, posortowane, odwrócone, zawierające liczby ujemne, duplikaty oraz przypadki graniczne, takie jak tablice puste czy jednoelementowe.
+  \item Dokumentacja użytkownika i programisty opisująca zarówno sposób korzystania z aplikacji, jak i techniczne aspekty implementacji oraz założenia projektowe.
+  \item Automatyzacja procesu testowania i budowania projektu dzięki zastosowaniu CMake, Ninja oraz GitHub Actions.
+  \item Wynikowy projekt, który może być uruchamiany na różnych systemach operacyjnych, takich jak Windows (z wykorzystaniem MINGW-w64) oraz Linux.
+\end{itemize}
+
+\subsection{Określenie ram projektowych}
+Projekt realizowany jest zgodnie z poniższymi wytycznymi:
+\begin{itemize}
+  \item Algorytm Merge Sort zostanie zaimplementowany jako osobna klasa \texttt{MergeSorter}, której funkcjonalności będą odpowiednio odseparowane od pozostałych modułów aplikacji.
+  \item Całość zostanie zaimplementowana z wykorzystaniem wzorców dobrych praktyk programistycznych, takich jak modularność, hermetyzacja kodu oraz dokumentowanie przy pomocy stylu Doxygen.
+  \item Testy jednostkowe pokrywające wszystkie krytyczne aspekty działania algorytmu zostaną umieszczone w pliku \texttt{merge\_sorter\_test.cpp}.
+  \item Dokumentacja będzie tworzona z użyciem szablonów i makr \texttt{LaTeX}, aby zapewnić spójność formatowania i estetyczny wygląd publikacji.
+\end{itemize}
+
+W dalszych rozdziałach omówiono szczegółowo implementację poszczególnych modułów projektu oraz uzyskane wyniki testów.

docs/dokumentacja/tex/rozdzial2.tex

@@ -1,6 +1,80 @@
 \newpage
-\section{Analiza problemu}		%2
-%Napisać gdzie używa się tego algorytmu
-%Opisać sposób działania programu/algorytmu
-%Napisać spsoób wykorzystania algorytmu po przez wykonanie przykładu (np. mnożenie macierzy - wykonać ręcznie przykład z mnożeniem macierzy pokazujący jak mnoży się macierz ręcznie)
-%Jeśli zadanie zakłada przedstawienie jakiegoś narzędzia (np. git, AI) należy opisać narzędzie
+\section{Analiza problemu}
+\label{sec:analiza-problemu}
+
+\subsection{Zastosowanie algorytmu sortowania przez scalanie}
+
+Algorytm sortowania przez scalanie (Merge Sort) jest jednym z najczęściej wykorzystywanych algorytmów do sortowania dużych zbiorów danych w informatyce. Jego główną zaletą jest stabilność i efektywność w przypadku dużych zbiorów danych. Jest to algorytm typu „dziel i zwyciężaj”, który dzieli zbiór na mniejsze podzbiory, a następnie scala je w sposób uporządkowany. Algorytm ten jest wykorzystywany \\ w różnych dziedzinach, takich jak:
+
+\begin{itemize}
+  \item Sortowanie dużych zbiorów danych w bazach danych.
+  \item Przetwarzanie danych w systemach rozproszonych, gdzie duże ilości danych muszą być uporządkowane przed dalszym przetwarzaniem.
+  \item Algorytmy związane z analizą danych, takie jak sortowanie wyników wyszukiwania.
+  \item Problemy związane z inżynierią oprogramowania, w których dane muszą być uporządkowane w sposób stabilny (np. przy sortowaniu użytkowników po wielu kryteriach).
+\end{itemize}
+
+W niniejszym projekcie zaimplementowano algorytm Merge Sort, który jest wykorzystywany do sortowania tablic liczb całkowitych.
+Program implementuje ten algorytm w języku C++, zapewniając jego elastyczność i możliwość testowania \\ w różnych scenariuszach.
+
+\subsection{Opis algorytmu sortowania przez scalanie}
+
+Algorytm Merge Sort działa na zasadzie podziału problemu na mniejsze podproblemy, co pozwala na efektywne sortowanie danych. Ogólny przebieg działania algorytmu przedstawia się następująco:
+
+\begin{enumerate}
+  \item Jeśli tablica ma więcej niż jeden element, dzielimy ją na dwie części (połowy).
+  \item Rekursywnie sortujemy każdą z części.
+  \item Po posortowaniu każdej z części, łączymy (scalamy) je w sposób uporządkowany w jedną, posortowaną tablicę.
+\end{enumerate}
+
+Przykład: Rozważmy tablicę liczb \texttt{[38, 27, 43, 3, 9, 82, 10]}. Algorytm Merge Sort wykonuje następujące kroki:
+
+\begin{enumerate}
+  \item Dzieli tablicę na dwie części: \texttt{[38, 27, 43]} i \texttt{[3, 9, 82, 10]}.
+  \item Każdą z części dzieli dalej, aż do uzyskania tablic jednowymiarowych:
+        \begin{itemize}
+          \item \texttt{[38, 27, 43]} → \texttt{[38, 27]} i \texttt{[43]} → \texttt{[38]} i \texttt{[27]} → \texttt{[38]} i \texttt{[27]}.
+          \item \texttt{[3, 9, 82, 10]} → \texttt{[3, 9]} i \texttt{[82, 10]} → \texttt{[3]} i \texttt{[9]} → \texttt{[3]} i \texttt{[9]} → \texttt{[82]} i \texttt{[10]}.
+        \end{itemize}
+  \item Następnie łączymy elementy w sposób uporządkowany:
+        \begin{itemize}
+          \item \texttt{[38]} i \texttt{[27]} → \texttt{[27, 38]}.
+          \item \texttt{[38, 27]} i \texttt{[43]} → \texttt{[27, 38, 43]}.
+          \item \texttt{[3]} i \texttt{[9]} → \texttt{[3, 9]}.
+          \item \texttt{[82]} i \texttt{[10]} → \texttt{[10, 82]}.
+          \item \texttt{[3, 9]} i \texttt{[10, 82]} → \texttt{[3, 9, 10, 82]}.
+        \end{itemize}
+  \item Na koniec scalamy dwie posortowane tablice:
+        \begin{itemize}
+          \item \texttt{[27, 38, 43]} i \texttt{[3, 9, 10, 82]} → \texttt{[3, 9, 10, 27, 38, 43, 82]}.
+        \end{itemize}
+\end{enumerate}
+
+Ostateczny wynik to posortowana tablica: \texttt{[3, 9, 10, 27, 38, 43, 82]}.
+
+\subsection{Sposób wykorzystania algorytmu w projekcie}
+
+W projekcie algorytm Merge Sort został zaimplementowany jako część klasy \texttt{MergeSorter}, której zadaniem jest sortowanie tablicy liczb całkowitych. Użytkownik może interaktywnie dodawać, usuwać lub tasować elementy w tablicy, a następnie uruchomić algorytm, aby posortować tablicę. Proces ten jest uproszczony do kilku kroków, które opisano poniżej.
+
+\begin{itemize}
+  \item Po uruchomieniu aplikacji użytkownik ma dostęp do menu, w którym może wybrać jedną z dostępnych operacji na tablicach.
+  \item Wybór opcji "Sortowanie" uruchamia algorytm Merge Sort, który wykonuje operację sortowania na aktualnej tablicy.
+  \item Użytkownik może także zainicjować generowanie losowej tablicy lub odwrócić kolejność elementów w tablicy, aby przeprowadzić sortowanie w różnych scenariuszach.
+  \item Po zakończeniu sortowania, wynikowa tablica zostaje wyświetlona na ekranie.
+\end{itemize}
+
+Przykład:
+1. Użytkownik generuje losową tablicę: \texttt{[38, 27, 43, 3, 9, 82, 10]}.
+2. Uruchamia sortowanie przez scalanie.
+3. Aplikacja wyświetla posortowaną tablicę: \texttt{[3, 9, 10, 27, 38, 43, 82]}.
+
+\subsection{Opis narzędzi i technologii użytych w projekcie}
+
+W projekcie zastosowano szereg narzędzi i technologii, które wspierają rozwój, testowanie oraz dokumentowanie aplikacji. Do głównych narzędzi należą:
+
+\begin{itemize}
+  \item \textbf{C++}: Język programowania użyty do implementacji algorytmu oraz aplikacji. C++ zapewnia wysoką wydajność, co jest istotne przy pracy z dużymi zbiorami danych.
+  \item \textbf{Google Test}: Framework do testowania jednostkowego w C++. Google Test umożliwia automatyczne uruchamianie testów oraz weryfikację poprawności działania algorytmu w różnych scenariuszach.
+  \item \textbf{CMake}: System budowania, który umożliwia generowanie plików konfiguracyjnych dla różnych środowisk kompilacji. CMake zapewnia elastyczność \\ w budowaniu projektu na różnych systemach operacyjnych.
+  \item \textbf{Doxygen}: Narzędzie do automatycznego generowania dokumentacji z komentarzy w kodzie. Doxygen pozwala na tworzenie dokumentacji technicznej \\ w formacie HTML lub PDF.
+  \item \textbf{GitHub Actions}: Narzędzie do automatyzacji procesów CI/CD. GitHub Actions służy do automatycznego uruchamiania testów, generowania dokumentacji i wdrażania aplikacji.
+\end{itemize}