From 67542a87c26a67b80e06dd02219b451dc3de73db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matt=C3=A9o=20Delabre=20=E2=9C=8F?= Date: Wed, 30 Nov 2016 11:55:10 +0100 Subject: [PATCH] Ajout de la documentation Doxygen --- Doxyfile | 9 ++++ inc/buffer.h | 123 ++++++++++++++++++++++++++++++++--------------- inc/common.h | 26 ++++++++-- inc/compress.h | 20 ++++++-- inc/decompress.h | 20 ++++++-- inc/display.h | 56 +++++++++++++++------ inc/huftree.h | 113 +++++++++++++++++++++++++++++-------------- 7 files changed, 267 insertions(+), 100 deletions(-) create mode 100644 Doxyfile diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..274250e --- /dev/null +++ b/Doxyfile @@ -0,0 +1,9 @@ +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = Huffman +PROJECT_NUMBER = 0.1 +PROJECT_BRIEF = "Compresseur Huffman en C, dans le cadre du projet HLIN303" + +OUTPUT_DIRECTORY = "./out/doxygen" +RECURSIVE = YES +OUTPUT_LANGUAGE = French +OPTIMIZE_OUTPUT_FOR_C = YES diff --git a/inc/buffer.h b/inc/buffer.h index 60e964d..45c25df 100644 --- a/inc/buffer.h +++ b/inc/buffer.h @@ -1,5 +1,14 @@ -#ifndef __IN303_BUFFER_H__ -#define __IN303_BUFFER_H__ +/** + * @file + * @brief Abstraction de l'écriture et la lecture d'un fichier bit à bit. + * + * Définir des structures et des fonctions de manipulation liées à + * un fichier et permettant d'accéder à son contenu ou de le modifier + * bit par bit au lieu d'octet par octet. + */ + +#ifndef __HUFFMAN_BUFFER_H_INCLUDED__ +#define __HUFFMAN_BUFFER_H_INCLUDED__ #include #include @@ -7,78 +16,114 @@ #include "common.h" /** + * @brief Tampon d'écriture bit par bit. + * * Tampon permettant d'abstraire l'écriture dans un fichier bit par * bit au lieu d'octet par octet. Les bits sont vidés dans le fichier - * dès qu'un octet est complet + * dès qu'un octet est complet, ou lorsque le vidage est forcé. */ -typedef struct WriteBuffer WriteBuffer; -struct WriteBuffer { - // Contient les données du tampon d'écriture, c'est-à-dire - // les données en attente de vidage dans le fichier +typedef struct WriteBuffer { + /** + * Données du tampon d'écriture en attente de vidage. + */ int data; - // Nombre de bits utilisés dans `data`. Si ce nombre vaut 8, - // le tampon d'écriture est plein + /** + * Nombre de bits utilisés dans WriteBuffer#data. + */ size_t pending_bits; - // Nombre d'octets écrits par le tampon d'écriture dans le - // fichier, correspondant au nombre de vidages du tampon + /** + * Nombre de vidages effectués par le tampon. + */ bytecount flushed_count; - // Fichier dans lequel le tampon d'éciture est vidé à l'appel - // de `flushBuffer` ou au débordement + /** + * Fichier dans lequel le tampon est vidé. + */ FILE* dest_file; -}; +} WriteBuffer; /** - * Initialise un tampon d'écriture vide, avec le fichier donné comme - * destination + * @brief Initialiser un tampon d'écriture. + * + * Initialiser un tampon vide avec le fichier @p dest pour destination. + * @param dest Fichier de destination. + * @return Tampon créé. */ -WriteBuffer createWriteBuffer(FILE*); +WriteBuffer createWriteBuffer(FILE* dest); /** - * Écrit le bit donné dans le tampon d'écriture + * @brief Écrire un bit dans le tampon d'écriture. + * + * Ajouter le bit @p bit aux données du tampon @p buffer. Si le tampon est + * plein, vidage dans le fichier associé. + * @param bit Bit à ajouter au tampon (0 ou 1). + * @param buffer Tampon dans lequel ajouter le bit. */ -void putBuffer(char bit, WriteBuffer*); +void putBuffer(char bit, WriteBuffer* buffer); /** - * Force le vidage du tampon dans son fichier et sa réinitialisation - * (les bits non-remplis seront remplacés par des 0) + * @brief Forcer le vidage du tampon d'écriture. + * + * Forcer le vidage du tampon dans son fichier et sa réinitialisation. + * Si le tampon est vide, pas de vidage (pas d'octet superflu écrit). + * Si le tampon n'est pas rempli, complétion à droite par des 0. + * @param buffer Tampon à vider. */ -void flushBuffer(WriteBuffer*); +void flushBuffer(WriteBuffer* buffer); /** - * Récupère le nombre de vidages effectués sur le tampon d'écriture, - * correspondant au nombre d'octets écrits par le tampon dans le fichier + * @brief Récupèrer le nombre de vidages effectués par ce tampon. + * + * Permet de savoir combien d'octets ont été écrits dans le fichier + * par le tampon @p buffer. + * @param buffer Tampon à vérifier. + * @return Nombre de vidages effectués. */ -bytecount getFlushedCount(WriteBuffer*); +bytecount getFlushedCount(WriteBuffer* buffer); /** - * Tampon permettant d'abstraire le lecture depuis un fichier bit par + * @brief Tampon de lecture bit par bit. + * + * Tampon permettant d'abstraire la lecture d'un fichier bit par * bit au lieu d'octet par octet. Un octet est lu depuis le fichier - * dès que tous les bits du précédent ont été lus + * seulement lorsque tous les bits du précédent octet ont été consommés. */ -typedef struct ReadBuffer ReadBuffer; -struct ReadBuffer { - // Contient les données du tampon de lecture, c'est-à-dire - // le dernier octet lu depuis le fichier +typedef struct ReadBuffer { + /** + * Données du tampon de lecture en attente de lecture. + */ int data; - // Numéro du prochain bit de `data` qui sera lu par `getBuffer` + /** + * Numéro du prochain bit de ReadBuffer#data à lire. + */ size_t next_bit; - // Fichier depuis lequel le tampon de lecture est rempli + /** + * Fichier depuis lequel les données sont lues. + */ FILE* source_file; -}; +} ReadBuffer; /** - * Initialise un tampon de lecture avec le fichier donné comme source + * @brief Initialiser un tampon de lecture. + * + * Initialiser un tampon vide avec le fichier @p source comme source. + * @param source Fichier source. + * @return Tampon créé. */ -ReadBuffer createReadBuffer(FILE*); +ReadBuffer createReadBuffer(FILE* source); /** - * Lit le prochain bit depuis le tampon de lecture + * @brief Lire un bit depuis le tampon de lecture. + * + * Lire le prochain bit depuis le tampon de lecture, et lire un octet + * depuis la source si besoin est. + * @param buffer Tampon depuis lequel lire un bit. + * @return Valeur du bit qui est lu : 0 ou 1. */ -char getBuffer(ReadBuffer*); +char getBuffer(ReadBuffer* buffer); -#endif +#endif // __HUFFMAN_BUFFER_H_INCLUDED__ diff --git a/inc/common.h b/inc/common.h index 2393aaa..272ee1e 100644 --- a/inc/common.h +++ b/inc/common.h @@ -1,10 +1,30 @@ -#ifndef __IN303_COMMON_H__ -#define __IN303_COMMON_H__ +/** + * @file + * @brief Définitions communes pour le reste du code. + */ +#ifndef __HUFFMAN_COMMON_H_INCLUDED__ +#define __HUFFMAN_COMMON_H_INCLUDED__ + +/** + * @brief Macro correspondant à la valeur booléenne vraie (1). + */ #define TRUE 1 + +/** + * @brief Macro correspondant à la valeur booléenne fausse (0). + */ #define FALSE 0 + +/** + * @brief Macro correspondant au nombre de caractères possibles. + */ #define NUM_CHARS 256 +/** + * @brief Alias du type d'entier non-signé 64 bits pour compter + * les longueurs de fichiers. + */ typedef long long unsigned int bytecount; -#endif +#endif // __HUFFMAN_COMMON_H_INCLUDED__ diff --git a/inc/compress.h b/inc/compress.h index 78e89d8..39031e7 100644 --- a/inc/compress.h +++ b/inc/compress.h @@ -1,8 +1,22 @@ -#ifndef __IN303_COMPRESS_H__ -#define __IN303_COMPRESS_H__ +/** + * @file + * @brief Compression des fichiers. + */ + +#ifndef __HUFFMAN_COMPRESS_H_INCLUDED__ +#define __HUFFMAN_COMPRESS_H_INCLUDED__ #include +/** + * @brief Compresser le fichier @p source vers @p dest. + * + * Lit les caractères de @p source, applique l'algorithme de Huffman pour + * déterminer une représentation compacte et la stocke dans @p dest. + * @param source Fichier ouvert en lecture depuis lequel lire les données. + * @param dest Fichier ouvert en écriture dans lequel écrire les données + * compressées. + */ void compress(FILE* source, FILE* dest); -#endif +#endif // __HUFFMAN_COMPRESS_H_INCLUDED__ diff --git a/inc/decompress.h b/inc/decompress.h index c3fb056..ae0997f 100644 --- a/inc/decompress.h +++ b/inc/decompress.h @@ -1,8 +1,22 @@ -#ifndef __IN303_DECOMPRESS_H__ -#define __IN303_DECOMPRESS_H__ +/** + * @file + * @brief Décompression des fichiers. + */ + +#ifndef __HUFFMAN_DECOMPRESS_H_INCLUDED__ +#define __HUFFMAN_DECOMPRESS_H_INCLUDED__ #include +/** + * @brief Décompresser le fichier @p source vers @p dest. + + * Lit le fichier @p source ayant été compressé avec l'algorithme de Huffman + * et écrit les données décompressées dans @p dest. + * @param source Fichier ouvert en lecture depuis lequel lire les données. + * @param dest Fichier ouvert en écriture dans lequel écrire les données + * décompressées. + */ void decompress(FILE* source, FILE* dest); -#endif +#endif // __HUFFMAN_DECOMPRESS_H_INCLUDED__ diff --git a/inc/display.h b/inc/display.h index 6148971..c16e3c1 100644 --- a/inc/display.h +++ b/inc/display.h @@ -1,45 +1,69 @@ -#ifndef __IN303_DISPLAY_H__ -#define __IN303_DISPLAY_H__ +/** + * @file + * @brief Gestion de l'affichage. + */ + +#ifndef __HUFFMAN_DISPLAY_H_INCLUDED__ +#define __HUFFMAN_DISPLAY_H_INCLUDED__ #include #include "common.h" +//! \{ typedef struct HufVertex HufVertex; typedef HufVertex* HufTree; +//! \} /** - * Écrire des données de débogage sur la sortie d'erreurs standard - * (seulement si le mode verbeux est actif) + * @brief Écrire un message de débogage sur la sortie d'erreurs. + * + * Cette fonction n'a aucun effet si l'affichage des messages de débogage + * ne sont pas activés, sinon le message est affiché dans @c stderr. + * @param format Format d'affichage à la printf. + * @param ... Variables pour l'affichage. */ void printVerbose(const char* format, ...); /** - * Active ou désactive l'affichage des messages de débogage (mode verbeux) - * sur la sortie d'erreurs standard + * @brief Activer ou désactiver l'affichage des messages de débogage. + * + * Si le paramètre est vrai, les appels suivants à @c printVerbose seront + * affichés sur la sortie d'erreurs. Sinon, ils n'auront aucun effet. + * @param enable Activer ou désactiver l'affichage. */ -void setVerbose(int); +void setVerbose(int enable); /** - * Renvoie l'état du mode verbeux + * @brief Vérifie si les messages de débogage sont activés ou non. */ int isVerbose(); /** - * Afficher sur la sortie standard l'arbre passé en paramètre + * @brief Afficher sur la sortie d'erreurs une représentation de l'arbre + * passé en paramètre. + * + * @param tree L'arbre à afficher. */ void printTree(HufTree tree); /** - * Afficher sur la sortie standard le tableau associant les caractères - * à leur effectif d'apparition passé en argument + * @brief Afficher sur la sortie d'erreurs le tableau associant les caractères + * à leur effectif d'apparition passé en argument. + * + * @param counts Tableau d'association des effectifs. + * @param total Nombre total de caractères. + * @param size Taille du tableau @p counts. */ -void printCountsTable(bytecount*, bytecount total, size_t); +void printCountsTable(bytecount* counts, bytecount total, size_t size); /** - * Afficher sur la sortie standard le tableau associant les caractères - * à leur étiquette passé en argument + * *@brief Afficher sur la sortie d'erreurs le tableau associant les caractères + * à leur étiquette passé en argument. + * + * @param labels Tableau d'association des étiquettes. + * @param size Taille du tableau @p labels. */ -void printLabelsTable(char**, size_t); +void printLabelsTable(char** labels, size_t size); -#endif +#endif // __HUFFMAN_DISPLAY_H_INCLUDED__ diff --git a/inc/huftree.h b/inc/huftree.h index a7dd95a..fe40f76 100644 --- a/inc/huftree.h +++ b/inc/huftree.h @@ -1,76 +1,117 @@ -#ifndef __IN303_HUFTREE_H__ -#define __IN303_HUFTREE_H__ +/** + * @file + * @brief Représentation mémoire des arbres binaires de Huffman. + * + * Définir une structure permettant de représenter en mémoire les + * arbres binaires de Huffman et des fonctions permettant de manipuler + * ces arbres. + */ + +#ifndef __HUFFMAN_HUFTREE_H_INCLUDED__ +#define __HUFFMAN_HUFTREE_H_INCLUDED__ #include #include #include "common.h" +//! \{ typedef struct WriteBuffer WriteBuffer; typedef struct ReadBuffer ReadBuffer; +//! \} /** - * Représente un des sommets d'un arbre de Huffman (représente l'arbre - * en entier s'il s'agit de la racine) + * @brief Sommet d'un arbre binaire de Huffman. + * + * Sommet possédant éventuellement une valeur (caractère associé), + * un effectif d'apparition (nombre d'occurences du caractère dans la source) + * et un sommet enfant à gauche et/ou à droite. */ -typedef struct HufVertex HufVertex; -typedef HufVertex* HufTree; -struct HufVertex { - // Caractère associé à ce sommet ou -1 s'il n'y a aucun caractère - // associé (notamment s'il s'agit d'une branche) +typedef struct HufVertex { + /** + * Caractère associé au sommet, ou -1 si aucun caractère + * n'est associé (par exemple pour les sommets internes). + */ unsigned int value; - // Indique l'effectif du caractère associée à ce sommet - // dans le fichier source, ou -1 s'il n'y a aucun caractère associé + /** + * Effectif du caractère associé au sommet, ou -1 si aucun + * caractère n'est associé. + */ bytecount count; - // Pointeurs vers les deux enfants de ce sommet. Ils valent tous - // deux NULL si le sommet est une feuille. À noter qu'un sommet - // a toujours 0 ou 2 enfants car un arbre de Huffman est binaire - HufVertex* child_l; - HufVertex* child_r; -}; + /** + * Sommet enfant à gauche, ou NULL si ce sommet n'a pas d'enfant + * à gauche. + */ + struct HufVertex* child_l; + + /** + * Sommet enfant à droite, ou NULL si ce sommet n'a pas d'enfant + * à droite. + */ + struct HufVertex* child_r; +} HufVertex; /** - * Construire un arbre de Huffman basé sur les effectifs - * de caractères passés dans `counts` + * @brief Arbre binaire de Huffman (pointeur vers un @c HufVertex) + */ +typedef HufVertex* HufTree; + +/** + * @brief Construire un arbre de Huffman. * - * (résultat à libérer avec `freeTree`) + * Lire les effectifs de caractères dans @p counts et en déduire + * un arbre binaire de Huffman. Le résultat doit être libéré avec + * la fonction @c freeTree. + * @param counts Comptes des caractères. + * @return Arbre construit. */ HufTree createTree(bytecount* counts); /** - * Écrit une représentation binaire de l'arbre dans le - * tampon passé en paramètre + * @brief Écrire un arbre dans le tampon d'écriture donné. + * + * Écrire une représentation binaire de l'arbre @p tree + * dans le tampon @p buffer. + * @param tree Arbre à représenter. + * @param buffer Tampon cible. */ -void writeTree(HufTree, WriteBuffer*); +void writeTree(HufTree tree, WriteBuffer* buffer); /** - * Reconstruit un arbre de Huffman à partir du fichier passé - * en paramètre + * @brief Lire un arbre depuis le tampon de lecture donné. + * + * Reconstruire un arbre de Huffman à partir du tampon de lecture + * @p buffer. Le résultat doit être libéré avec la fonction @c freeTree. + * @return L'arbre reconstruit. */ -HufTree readTree(ReadBuffer*); +HufTree readTree(ReadBuffer* buffer); /** - * Libérer la mémoire occupée par un arbre de Huffman - * généré par la fonction `createTree` + * @brief Libérer la mémoire occupée par un arbre. + * @param tree Arbre à libérer. */ void freeTree(HufTree tree); /** - * Associer à chaque feuille de l'arbre une étiquette unique basée - * sur sa position dans l'arbre. Aucune étiquette n'est ainsi préfixe - * d'une autre. Le tableau renvoyé associe chaque caractère ASCII - * à son préfixe, ou à NULL s'il n'est pas présent dans l'arbre + * @brief Créer la clé de codage à partir d'un arbre de Huffman. * - * (résultat à libérer avec `freeTreeLabels`) + * Associer à chaque feuille de l'arbre une étiquette unique basée sur + * sa position dans l'arbre. Aucune étiquette n'est ainsi préfixe d'une + * autre. Le tableau renvoyé associe chaque caractère ASCII à son préfixe + * ou à NULL s'il n'est pas présent dans l'arbre. Le résultat doit être + * libéré avec @c freeTreeLabels. + * + * @param tree Arbre source de la clé de codage. + * @return Clé générée. */ char** createTreeLabels(HufTree tree); /** - * Libérer la mémoire occupée par un tableau d'étiquettes renvoyé - * par la fonction `labelTree` + * @brief Libérer la mémoire occupée par une clé de codage. + * @param labels Clé à libérer. */ void freeTreeLabels(char** labels); -#endif +#endif // __HUFFMAN_HUFTREE_H_INCLUDED__