From ae74134064b9c6ba65818c138704374ae810a52a Mon Sep 17 00:00:00 2001 From: Phuntsok Drak-pa Date: Sat, 24 Nov 2018 22:41:29 +0100 Subject: [PATCH] fixed documentation --- doc/Doxyfile | 2 +- src/compress.c | 10 +++--- src/compress.h | 2 +- src/darray.c | 30 ++++++++-------- src/darray.h | 6 ++-- src/errorcodes.h | 8 ++--- src/ppm.c | 90 ++++++++++++++++++++++++++---------------------- src/ppm.h | 22 ++++++------ src/utilities.c | 27 +++++++-------- src/utilities.h | 8 ++--- 10 files changed, 106 insertions(+), 99 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index c73c8cf..4d1ab1c 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -1997,7 +1997,7 @@ PERLMOD_MAKEVAR_PREFIX = # C-preprocessor directives found in the sources and include files. # The default value is: YES. -ENABLE_PREPROCESSING = NO +ENABLE_PREPROCESSING = YES # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names # in the source code. If set to NO, only conditional compilation will be diff --git a/src/compress.c b/src/compress.c index cf856ea..71c031c 100644 --- a/src/compress.c +++ b/src/compress.c @@ -1,5 +1,5 @@ /** - * \file common.c + * \file compress.c * \brief Implémentation de la (dé)compression d’images */ @@ -80,7 +80,7 @@ void addPixelToSelectedZone(Image *t_img, int64_t t_idx, Zone *t_zone) { * \param[in] t_idx Index du pixel à tester * \param[out] t_zones Liste des zones de l’image */ -void chooseZoneForPixel(Image *t_img, int64_t t_idx, darray *zones) { +void chooseZoneForPixel(Image *t_img, int64_t t_idx, darray *t_zones) { Zone *current_zone; Pixel *pixel; size_t i; @@ -91,8 +91,8 @@ void chooseZoneForPixel(Image *t_img, int64_t t_idx, darray *zones) { return; } /* for each known zone, see if it matches the current pixel's color */ - for (i = 0; i < darraySize(zones); ++i) { - current_zone = darrayGet(zones, i); + for (i = 0; i < darraySize(t_zones); ++i) { + current_zone = darrayGet(t_zones, i); /* if it does, add selected pixel and its neighbouring pixels of the same * color */ if (sameColor(pixel, current_zone)) { @@ -104,7 +104,7 @@ void chooseZoneForPixel(Image *t_img, int64_t t_idx, darray *zones) { * and add the selected pixel and its neighbours of the same color to the zone */ current_zone = newZone(pixel->r, pixel->g, pixel->b); - darrayPushBack(zones, current_zone); + darrayPushBack(t_zones, current_zone); addPixelToSelectedZone(t_img, t_idx, current_zone); } diff --git a/src/compress.h b/src/compress.h index 719434f..c5ace1e 100644 --- a/src/compress.h +++ b/src/compress.h @@ -1,5 +1,5 @@ /** - * \file common.h + * \file compress.h * \brief Déclaration pour la (dé)compression d’images */ diff --git a/src/darray.c b/src/darray.c index 7b9306a..e1454dd 100644 --- a/src/darray.c +++ b/src/darray.c @@ -14,7 +14,7 @@ * tableau. Cela implique qu’un objet \ref darray ne peut contenir que des * éléments du même type. * - * \param[in] element_size Taille des objets stockés + * \param[in] t_element_size Taille des objets stockés * \return Pointeur sur le nouvel objet \ref darray */ darray *darrayNew(size_t t_element_size) { @@ -34,10 +34,10 @@ darray *darrayNew(size_t t_element_size) { * élément. Cette fonction modifie les membres `begin` et `end` et * potentiellement `capacity` de `self`. * - * \param[in] self Objet \ref darray dans lequel on souhaite insérer un nouvel + * \param[in] t_self Objet \ref darray dans lequel on souhaite insérer un nouvel * élément - * \param[in] pos Position à laquelle on souhaite insérer un nouvel élément - * \param[in] elem Élément que l’on souhaite insérer + * \param[in] t_pos Position à laquelle on souhaite insérer un nouvel élément + * \param[in] t_elem Élément que l’on souhaite insérer */ void darrayInsert(darray *t_self, void *t_pos, void *t_elem) { char *itr; @@ -57,7 +57,7 @@ void darrayInsert(darray *t_self, void *t_pos, void *t_elem) { * sa capacité par deux. Si la réallocation mémoire ne réussit pas, le * programme s’arrête immédiatement, renvoyant la valeur de \ref PTR_ERROR * - * \param[in] self L'objet darray à étendre + * \param[in] t_self L'objet darray à étendre */ void darrayExtend(darray *t_self) { void *new_array; @@ -82,8 +82,8 @@ void darrayExtend(darray *t_self) { * entre les membres `begin` et `end` de `self`. Par ailleurs, le membre `end` * de `self` se retrouve modifié par la fonction. * - * \param[out] self Objet \ref `darray` dont on souhaite supprimer un élément - * \param[in] pos Élément de `self` que l’on souhaite supprimer + * \param[out] t_self Objet \ref darray dont on souhaite supprimer un élément + * \param[in] t_pos Élément de `self` que l’on souhaite supprimer */ void darrayErase(darray *t_self, void *t_pos) { memmove(t_pos, (char *)t_pos + t_self->element_size, @@ -95,9 +95,9 @@ void darrayErase(darray *t_self, void *t_pos) { * `darrayPushBack` ajoute un nouvel élément `elem` à l’objet `self` à la fin du * tableau de ce dernier. Cette fonction modifie le membre `end` de `self`. * - * \param[out] self Objet \ref darray à la fin duquel on souhaite ajouter un + * \param[out] t_self Objet \ref darray à la fin duquel on souhaite ajouter un * nouvel élément - * \param[in] elem Élément que l’on souhaite ajouter à la fin de `self` + * \param[in] t_elem Élément que l’on souhaite ajouter à la fin de `self` */ void darrayPushBack(darray *t_self, void *t_elem) { darrayInsert(t_self, t_self->end, t_elem); @@ -108,7 +108,7 @@ void darrayPushBack(darray *t_self, void *t_elem) { * darray passé en argument. Cette fonction modifie le membre `end` de ce * dernier objet. * - * \param[out] self Objet dont on souhaite supprimer le dernier élément + * \param[out] t_self Objet dont on souhaite supprimer le dernier élément */ void darrayPopBack(darray *t_self) { darrayErase(t_self, (char *)t_self->end - t_self->element_size); @@ -120,7 +120,7 @@ void darrayPopBack(darray *t_self) { * L’objet passé en argument ne sera plus utilisable après utilisation de cette * fonction. * - * \param[out] self Objet \ref darray à supprimer + * \param[out] t_self Objet \ref darray à supprimer */ void darrayDelete(darray *t_self) { free(t_self->begin); @@ -132,7 +132,7 @@ void darrayDelete(darray *t_self) { * `self` passé en arguments. Cette fonction ne modifie pas l’élément passé en * argument. * - * \param[out] self Objet \ref darray dont on souhaite connaître le nombre + * \param[out] t_self Objet \ref darray dont on souhaite connaître le nombre * d’éléments * \return Nombre d’éléments contenus dans `self` */ @@ -147,9 +147,9 @@ size_t darraySize(darray *t_self) { * le pointeur `NULL` sera renvoyé, sinon un pointeur de type `void*` pointant * sur l’élément correspondant sera renvoyé. Cette fonction ne modifie pas * l’objet `self`. - * \param[out] self Objet \ref darray duquel on souhaite obtenir un pointeur sur - * l’élément à l’index `idx` - * \param[in] idx Index de l’élément que l’on souhaite récupérer + * \param[out] t_self Objet \ref darray duquel on souhaite obtenir un pointeur + * sur l’élément à l’index `idx` + * \param[in] t_idx Index de l’élément que l’on souhaite récupérer * \return Pointeur de type `void*` pointant sur l’élément si l’index est * valide, sur NULL sinon. */ diff --git a/src/darray.h b/src/darray.h index 0b75e7f..2b3999e 100644 --- a/src/darray.h +++ b/src/darray.h @@ -11,13 +11,13 @@ #include /** - * \struct darray_s + * \struct darray * \brief Tableau dynamique * - * Les objets `darray_s` offrent la possibilité d’avoir des tableaux à taille + * Les objets `darray` offrent la possibilité d’avoir des tableaux à taille * variable en C, similairement aux objets `vector` en C++. */ -typedef struct darray_s { +typedef struct { void *begin; /*!< Pointeur sur le premier élément du tableau */ void *end; /*!< Pointeur sur l’élément situé immédiatement après le dernier élément du tableau */ diff --git a/src/errorcodes.h b/src/errorcodes.h index ec4b7ab..a39a96a 100644 --- a/src/errorcodes.h +++ b/src/errorcodes.h @@ -1,9 +1,9 @@ /** - * \file errorcodes.h - * \brief Definition of error codes + * \file errorcodes.h + * \brief Definition of error codes * - * Dans ce fichier sont définis les codes d’erreur pouvant interrompre le - * programme. + * Dans ce fichier sont définis les codes d’erreur pouvant interrompre le + * programme. */ #ifndef SRC_ERRORCODES_H_ diff --git a/src/ppm.c b/src/ppm.c index e322893..0d656de 100644 --- a/src/ppm.c +++ b/src/ppm.c @@ -19,8 +19,8 @@ * `1`. En cas de succès, la fonction renverra un pointeur de fichier vers le * fichier ouvert. * - * \param[in] filename Nom du fichier à ouvrir - * \param[in] mode Mode du fichier à ouvrir + * \param[in] t_filename Nom du fichier à ouvrir + * \param[in] t_mode Mode du fichier à ouvrir * \return Pointeur de fichier */ FILE *get_file(const char *t_filename, const char *t_mode) { @@ -36,8 +36,8 @@ FILE *get_file(const char *t_filename, const char *t_mode) { * Lit et vérifie le format du fichier passé en argument. Si le format n’est * pas correct, la fonction arrête le processus qui renverra la valeur `1`. * - * \param[in] fb Fichier ppm où lire les données - * \param[in] filename Nom du fichier ouvert + * \param[in] t_fp Fichier ppm où lire les données + * \param[in] t_filename Nom du fichier ouvert */ void read_file_format(FILE *t_fp, const char *t_filename) { char buff[16]; @@ -55,7 +55,7 @@ void read_file_format(FILE *t_fp, const char *t_filename) { /** * Vérifie si le header contient des commentaires et les ignore le cas échéant. * - * \param[in] fp Fichier ppm où lire les données + * \param[in] t_fp Fichier ppm où lire les données */ void check_for_comments(FILE *t_fp) { char c; @@ -72,9 +72,9 @@ void check_for_comments(FILE *t_fp) { * Lit la taille des données image et les écrit dans le conteneur d’images * passé en argument. * - * \param[in] fp Fichier ppm où lire les données - * \param[out] img Conteneur d’image où écrire les résultats - * \param[in] filename Nom du fichier ouvert + * \param[in] t_fp Fichier ppm où lire les données + * \param[out] t_img Conteneur d’image où écrire les résultats + * \param[in] t_filename Nom du fichier ouvert */ void read_file_size(FILE *t_fp, Image *t_img, const char *t_filename) { if (fscanf(t_fp, "%lu %lu", &t_img->x, &t_img->y) != 2) { @@ -87,8 +87,8 @@ void read_file_size(FILE *t_fp, Image *t_img, const char *t_filename) { * Vérifie le format RGB de l’image ppm. Si le format n’est pas correct, la * fonction arrête le processus qui renverra la valeur `1`. * - * \param[in] fp Fichier ppm où lire les données - * \param[in] filename Nom du fichier ouvert + * \param[in] t_fp Fichier ppm où lire les données + * \param[in] t_filename Nom du fichier ouvert */ void read_rgb(FILE *t_fp, const char *t_filename) { char d; @@ -106,24 +106,28 @@ void read_rgb(FILE *t_fp, const char *t_filename) { } } -unsigned long read_data(FILE *t_fp, Image *t_img, unsigned char **t_data, - const char *t_filename) { - unsigned long size; - /* allocation memoire */ - size = t_img->x * t_img->y * 3; - DEBUG { - printf("Size image %lu %lu => %lu\n", t_img->x, t_img->y, - t_img->x * t_img->y); - } - *t_data = (unsigned char *)malloc((size_t)size * sizeof(unsigned char)); +/** + * \brief function description + * + * Lit les données images brutes du fichier ppm ouvert et les stocke dans \p + * t_data. + * + * \param[in] t_fp Fichier ppm ouvert source + * \param[in] t_size Taille des données brutes + * \param[out] t_data Pointeur vers le tableau de sortie des données brutes + * \param[in] t_filename Nom du fichier d’entrée + * \return Taille du tableau de données obtenu + */ +void read_data(FILE *t_fp, uint64_t t_size, unsigned char **t_data, + const char *t_filename) { + *t_data = (unsigned char *)malloc(t_size * sizeof(unsigned char)); assert(*t_data); /* read pixel data from file */ - if (!fread(*t_data, (size_t)1, (size_t)size, t_fp)) { + if (!fread(*t_data, (size_t)1, t_size, t_fp)) { fprintf(stderr, "Error loading image '%s'\n", t_filename); free(*t_data); exit(FILE_IO_ERROR); } - return size; } /** @@ -132,12 +136,11 @@ unsigned long read_data(FILE *t_fp, Image *t_img, unsigned char **t_data, * tableau de pixels multipliée par trois du fait des trois emplacements séparés * par couleur. * - * \param[out] img Image dont les pixels doivent être convertis - * \param[in] data Données à convertir en structures \ref Pixel - * \param[in] size Taille du tableau de `unsigned char` - * \return return type + * \param[out] t_img Image dont les pixels doivent être convertis + * \param[in] t_data Données à convertir en structures \ref Pixel + * \param[in] t_size Taille du tableau de `unsigned char` */ -void dataToImage(Image *t_img, unsigned char *t_data, unsigned long t_size) { +void dataToImage(Image *t_img, uint8_t *t_data, uint64_t t_size) { unsigned long i; t_img->pixels = darrayNew(sizeof(Pixel)); printf("Size of data: %lu\n", t_size); @@ -149,18 +152,18 @@ void dataToImage(Image *t_img, unsigned char *t_data, unsigned long t_size) { /** * Convertit le vecteur de pixels d’un conteneur d’image en un tableau de - * valeurs de type `GLuint` afin de permettre l’écriture d’une image dans un + * valeurs de type `uint8_t` afin de permettre l’écriture d’une image dans un * fichier. * - * \param[in] img Conteneur d’image contenant les pixels à convertir - * \return Tableau de pointeurs de `GLuint` + * \param[in] t_img Conteneur d’image contenant les pixels à convertir + * \return Tableau de pointeurs de `uint8_t` */ -unsigned char *imageToData(Image *t_img) { +uint8_t *imageToData(Image *t_img) { Pixel *pixel; - unsigned char *data, size; + uint8_t *data, size; unsigned long i; - size = (unsigned char)darraySize(t_img->pixels); - data = (unsigned char *)malloc(3 * sizeof(unsigned char) * size); + size = (uint8_t)darraySize(t_img->pixels); + data = (uint8_t *)malloc(3 * sizeof(uint8_t) * size); for (i = 0; i < size; i += 3) { pixel = darrayGet(t_img->pixels, i / 3); data[i] = pixel->r; @@ -176,20 +179,25 @@ unsigned char *imageToData(Image *t_img) { * lequel les données et l'image seront manipulables. Retourne la valeur 1 en * cas de succès. * - * \param[in] filename Nom du fichier image à ouvrir - * \param[out] img Objet \ref Image manipulable + * \param[in] t_filename Nom du fichier image à ouvrir + * \param[out] t_img Objet \ref Image manipulable * \return Retourne 1 en cas de succès */ int imageLoadPPM(const char *t_filename, Image *t_img) { FILE *fp; - unsigned long size; + uint64_t size; unsigned char *data = NULL; fp = get_file(t_filename, "rb"); /* open PPM file for reading */ read_file_format(fp, t_filename); /* read image format */ check_for_comments(fp); /* check for comments */ read_file_size(fp, t_img, t_filename); /* read image size information */ read_rgb(fp, t_filename); /* read rgb component */ - size = read_data(fp, t_img, &data, t_filename); /* read data from file */ + DEBUG { + printf("Size image %lu %lu => %lu\n", t_img->x, t_img->y, + t_img->x * t_img->y); + } + size = t_img->x * t_img->y * 3; + read_data(fp, size, &data, t_filename); /* read data from file */ dataToImage(t_img, data, size); free(data); fclose(fp); @@ -200,12 +208,12 @@ int imageLoadPPM(const char *t_filename, Image *t_img) { () * Ouvre le fichier image avec son nom de fichier passé par le paramètre * `filename` et y écrit les informations trouvées dans l’objet `img`. * - * \param[in] filename Nom du fichier image à ouvrir - * \param[in] img Objet \ref Image à écrire + * \param[in] t_filename Nom du fichier image à ouvrir + * \param[in] t_img Objet \ref Image à écrire */ void imageSavePPM(char *t_filename, Image *t_img) { FILE *fp; - unsigned char *data; + uint8_t *data; fp = get_file(t_filename, "wb"); /* open file for output */ /* write the header file */ fprintf(fp, "P6\n"); /* image format */ diff --git a/src/ppm.h b/src/ppm.h index 2f0ca7f..7462e92 100644 --- a/src/ppm.h +++ b/src/ppm.h @@ -13,25 +13,25 @@ #include "utilities.h" /// \brief Ouvre un fichier avec les autorisations demandées -FILE *get_file(const char *filename, const char *mode); +FILE *get_file(const char *t_filename, const char *t_mode); /// \brief Lit le format d’un fichier ppm ouvert -void read_file_format(FILE *fp, const char *filename); +void read_file_format(FILE *t_fp, const char *t_filename); /// \brief Vérifie et ignore d’éventuels commentaires du header d’un fichier -void check_for_comments(FILE *fp); +void check_for_comments(FILE *t_fp); /// \brief Lit les dimensions du fichier ppm ouvert -void read_file_size(FILE *fp, Image *img, const char *filename); +void read_file_size(FILE *t_fp, Image *t_img, const char *t_filename); /// \brief Lit et vérifie le format RGB du fichier ppm -void read_rgb(FILE *fp, const char *filename); +void read_rgb(FILE *t_fp, const char *t_filename); /// \brief Lit dans le conteneur les données images du fichier ppm -unsigned long read_data(FILE *fp, Image *img, unsigned char **data, - const char *filename); +void read_data(FILE *t_fp, uint64_t t_size, uint8_t **t_data, + const char *t_filename); /// \brief Convertit les données brutes de fichier vers des conteneurs de pixels -void dataToImage(Image *img, unsigned char *data, unsigned long size); +void dataToImage(Image *t_img, uint8_t *t_data, uint64_t t_size); /// \brief Convertit les pixels d’une image en tableau natif OpenGL -unsigned char *imageToData(Image *img); +unsigned char *imageToData(Image *t_img); /// \brief Ouverture et lecture de l’image d’entrée -int imageLoadPPM(const char *filename, Image *img); +int imageLoadPPM(const char *t_filename, Image *t_img); /// \brief Ouverture et écriture de l'image de sortie -void imageSavePPM(char *filename, Image *img); +void imageSavePPM(char *t_filename, Image *t_img); #endif /* SRC_PPM_H_ */ diff --git a/src/utilities.c b/src/utilities.c index 4d66533..c9f0997 100644 --- a/src/utilities.c +++ b/src/utilities.c @@ -13,9 +13,9 @@ * Créé un nouveau pixel initialisé avec les arguments `r`, `g` et `b` et * renvoie un pointeur vers ce pixel créé. * - * \param[in] r Valeur rouge du pixel - * \param[in] g Valeur verte du pixel - * \param[in] b Valeur bleue du pixel + * \param[in] t_r Valeur rouge du pixel + * \param[in] t_g Valeur verte du pixel + * \param[in] t_b Valeur bleue du pixel * \return Pointeur sur une structure de type \ref Pixel */ Pixel *newPixel(uint8_t t_r, uint8_t t_g, uint8_t t_b) { @@ -50,7 +50,7 @@ Image *newImage() { * destructeur libérera la structure \ref Image pointée par le pointeur passé * en argument. * - * \param[in] self Conteneur d’image à détruire + * \param[in] t_self Conteneur d’image à détruire */ void deleteImage(Image *t_self) { DEBUG { printf("deleted all pixels\n"); } @@ -63,15 +63,14 @@ void deleteImage(Image *t_self) { * valeurs qu’il contiendra avec les arguments qui lui seront passés lors de * l’appel de la fonction. * - * \param[in] y Ordonnée à laquelle le segment réside - * \param[in] xd Abscisse extrême droite du segment - * \param[in] xg Abscisse extrême gauche du segment + * \param[in] t_right_limit Abscisse extrême droite du segment + * \param[in] t_left_limit Abscisse extrême gauche du segment * \return Pointeur sur un conteneur de segment */ -Segment *newSegment(uint32_t t_xd, uint32_t t_xg) { +Segment *newSegment(uint32_t t_right_limit, uint32_t t_left_limit) { Segment *res = (Segment *)malloc(sizeof(Segment)); - res->xd = t_xd; - res->xg = t_xg; + res->right_limit = t_right_limit; + res->left_limit = t_left_limit; return res; } @@ -82,9 +81,9 @@ Segment *newSegment(uint32_t t_xd, uint32_t t_xg) { * de la zone et initialise un tableau dynamique vide de \ref Segment. Renvoie * un pointeur vers la structure nouvellement créée. * - * \param[in] r Valeur rouge de la couleur de la zone - * \param[in] g Valeur verte de la couleur de la zone - * \param[in] b Valeur bleue de la couleur de la zone + * \param[in] t_r Valeur rouge de la couleur de la zone + * \param[in] t_g Valeur verte de la couleur de la zone + * \param[in] t_b Valeur bleue de la couleur de la zone * \return Pointeur vers la structure créée */ Zone *newZone(uint8_t t_r, uint8_t t_g, uint8_t t_b) { @@ -100,6 +99,6 @@ Zone *newZone(uint8_t t_r, uint8_t t_g, uint8_t t_b) { * Destructeur de zone, libère la zone mémoire utilisée pour stocker les * segments. Ne libère pas \p t_self lui-même mais son membre `segments`. * - * \param[in] self Conteneur de zone à détruire + * \param[in] t_self Conteneur de zone à détruire */ void deleteZoneContent(Zone *t_self) { darrayDelete(t_self->segments); } diff --git a/src/utilities.h b/src/utilities.h index 18c463a..bb17a0d 100644 --- a/src/utilities.h +++ b/src/utilities.h @@ -67,7 +67,7 @@ struct Pixel { uint8_t r; /*!< Couleur rouge du pixel */ uint8_t g; /*!< Couleur verte du pixel */ uint8_t b; /*!< Couleur bleue du pixel */ - unsigned char visited; /*!< Le pixel a-t-il été visité avant */ + uint8_t visited; /*!< Le pixel a-t-il été visité avant */ }; /** @@ -91,8 +91,8 @@ struct Zone { * à son extrême droite et à son extrême gauche. */ struct Segment { - uint32_t xd; /*!< extrême droit du segment */ - uint32_t xg; /*!< extrême gauche du segment */ + uint32_t right_limit; /*!< extrême droit du segment */ + uint32_t left_limit; /*!< extrême gauche du segment */ }; /*****************************************************************************/ @@ -106,7 +106,7 @@ Image *newImage(); /// \brief Destructeur d’une image void deleteImage(Image *t_self); /// \brief Constructeur d’un segment de couleur unie -Segment *newSegment(uint32_t t_xd, uint32_t t_xg); +Segment *newSegment(uint32_t t_right_limit, uint32_t t_left_limit); /// \brief Constructeur de conteneur de zone Zone *newZone(uint8_t t_r, uint8_t t_g, uint8_t t_b); /// \brief Destructeur de conteneur de zone