From b330cf15d141824ba042d0013213761f06a061a4 Mon Sep 17 00:00:00 2001
From: Unbewohnte <me@unbewohnte.su>
Date: Tue, 19 Dec 2023 21:30:32 +0300
Subject: [PATCH] documentation: algebraic_notation

---
 TODO                     |  6 +++---
 src/algebraic_notation.c | 19 +++++++++++++++++--
 src/algebraic_notation.h | 12 +++++++++++-
 3 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/TODO b/TODO
index a886bea..0372896 100644
--- a/TODO
+++ b/TODO
@@ -1,4 +1,4 @@
 1. Algebraic notation: notation_move_to_string, documentation
-2. Board: board_is_move_legal, add other piece's moves
-3. Chess: output special error message for each type of illegal move so it's clear what went wrong
-4. board_get_pawn_moves - add en passant
\ No newline at end of file
+2. Chess: output special error message for each type of illegal move so it's clear what went wrong
+3. board_get_pawn_moves - add en passant
+4. board_get_king_moves - add castling
\ No newline at end of file
diff --git a/src/algebraic_notation.c b/src/algebraic_notation.c
index 8f8eca3..5e9a5a7 100644
--- a/src/algebraic_notation.c
+++ b/src/algebraic_notation.c
@@ -71,6 +71,7 @@ Position notation_tile_to_position(TileNotation notation) {
 }
 
 
+// Converts notated tile into its string representation
 char* notation_tile_to_string(TileNotation tile) {
     char* notation = (char*) malloc(sizeof(char) * 2);
     if (!notation) {
@@ -83,6 +84,8 @@ char* notation_tile_to_string(TileNotation tile) {
     return notation;
 }
 
+
+// Converts notated tile into its string representation on dest
 void notation_tile_to_string_cpy(TileNotation tile, char* dest) {
     if (!dest) {
         return;
@@ -96,6 +99,7 @@ void notation_tile_to_string_cpy(TileNotation tile, char* dest) {
 }
 
 
+// Converts notated tile string into its corresponding structure
 TileNotation notation_tile_from_string(const char* tile_string) {
     if (!tile_string) {
         return notation_tile_new('a', 1);
@@ -109,6 +113,7 @@ TileNotation notation_tile_from_string(const char* tile_string) {
 }
 
 
+// Creates a new notation tile from given file and rank. 
 TileNotation notation_tile_new(char file, unsigned int rank) {
     TileNotation tile;
     tile.file = file;
@@ -118,7 +123,7 @@ TileNotation notation_tile_new(char file, unsigned int rank) {
 }
 
 
-// Converts
+// Converts position to a notated position
 TileNotation notation_tile_from_pos(Position pos) {
     TileNotation tile;    
     switch (pos.row) {
@@ -263,6 +268,7 @@ Piece notation_piece_from_char(char character) {
 }
 
 
+// Converts notated move into its string representation
 char* notation_move_to_string(MoveNotation move) {
     char* move_notation = (char*) malloc(sizeof(char) * 10);
     if (!move_notation) {
@@ -371,7 +377,16 @@ MoveNotation* notation_move_from_string(const char* move_string) {
 }
 
 
-MoveNotation notation_move_new(Piece piece, TileNotation origin, TileNotation target, int move_type);
+// Creates a new move notation from provided arguments
+MoveNotation notation_move_new(Piece piece, TileNotation origin, TileNotation target, int move_type) {
+    MoveNotation move_new;
+    move_new.piece = piece;
+    move_new.origin = origin;
+    move_new.target = target;
+    move_new.move_type = move_type;
+
+    return move_new;
+}
 
 
 // Converts move notation to a move
diff --git a/src/algebraic_notation.h b/src/algebraic_notation.h
index bb7ae58..209ed61 100644
--- a/src/algebraic_notation.h
+++ b/src/algebraic_notation.h
@@ -26,6 +26,7 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 #include "move.h"
 
 
+// A notated tile representation
 typedef struct TileNotation {
     char file;
     unsigned int rank;
@@ -36,19 +37,23 @@ typedef struct TileNotation {
 Position notation_tile_to_position(TileNotation notation);
 
 
+// Converts notated tile into its string representation
 char* notation_tile_to_string(TileNotation tile);
 
 
+// Converts notated tile into its string representation on dest
 void notation_tile_to_string_cpy(TileNotation tile, char* dest);
 
 
+// Converts notated tile string into its corresponding structure
 TileNotation notation_tile_from_string(const char* tile_string);
 
 
+// Creates a new notation tile from given file and rank. 
 TileNotation notation_tile_new(char file, unsigned int rank);
 
 
-// Converts
+// Converts position to a notated position
 TileNotation notation_tile_from_pos(Position pos);
 
 
@@ -66,6 +71,7 @@ Big characters are for WHITE pieces, small for BLACK pieces.
 Piece notation_piece_from_char(char character);
 
 
+// A notated move representation
 typedef struct MoveNotation {
     Piece piece;
     TileNotation origin;
@@ -74,6 +80,7 @@ typedef struct MoveNotation {
 } MoveNotation;
 
 
+// Converts notated move into its string representation
 char* notation_move_to_string(MoveNotation move);
 
 
@@ -90,6 +97,9 @@ Returns NULL if technical errors were encountered, move_string does not contain
 MoveNotation* notation_move_from_string(const char* move_string);
 
 
+/*
+Creates a new move notation from provided arguments
+*/
 MoveNotation notation_move_new(Piece piece, TileNotation origin, TileNotation target, int move_type);