Fork 0

Add some documentation

- Document hvif-light.h
- Partialy document hvif-cairo.h
- Tweak Doxyfile
This commit is contained in:
Hans-Joerg Schurr 2020-05-05 00:07:39 +02:00
parent 4ebb4d8379
commit 70fa69c465
4 changed files with 63 additions and 11 deletions

.gitignore vendored
View File

@ -20,6 +20,7 @@ src/src

View File

@ -895,7 +895,7 @@ RECURSIVE = NO
# Note that relative paths are relative to the directory from which doxygen is
# run.
EXCLUDE = @srcdir@/config.h
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
@ -1492,7 +1492,7 @@ DISABLE_INDEX = NO
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
# doxygen will group on one line in the generated HTML documentation.

View File

@ -1,3 +1,18 @@
* \file hvif-cairo.h
* \author Hans-Jörg Schurr
* \brief An experimental renderer for \a hvif images based on cairo.
* This library provides functions for rendering \a hvif images with cairo.
* The rendere is incomplete and serves only as a vehicle to understand the
* semantic of \a hvif images. In general it only attempts to render
* features exposed by Icon-o-Matic. Furthermore multiple stroke transforms
* and contour transforms are not supported. Furthermore the colour space
* is not equivalent to the colour space used on Haiku. The renderer is only
* lightly tested and most likely contains horrible bugs.
#ifndef HVIF_CAIRO_H
#define HVIF_CAIRO_H

View File

@ -1,30 +1,66 @@
* \file hvif-light.h
* \author Hans-Jörg Schurr
* \brief Parse \a hvif images.
* This library provides functions for parsing Haiku Vector Icon
* files. The parser should be able to parse any files generated by Haiku
* as of April 2020. It is, however, wholly untested and should not be
* used. It most likely contains horrible bugs. During parsing some
* basic checks for consistency of the image data are performed. But
* not everything is checked. For example, paths might be invalid.
#ifndef HVIF_LIGHT_H
#define HVIF_LIGHT_H
#include <stdbool.h>
#include <stdio.h>
/** \typedef The result of parsing an image. */
typedef enum hvif_status
SUCCESS = 0, /**< The image has been parsed into memory. */
ERROR_EOF, /**< The file ended before parsing finished. */
ERROR_NOMEM, /**< Not enough memory could be allocated. */
ERROR_MAGIC, /**< The magic number of the file is wrong. */
ERROR_STYLE, /**< Parsing a style failed. */
ERROR_PATH, /**< Parsing a path failed. */
ERROR_SHAPE /**< Parsing a shape failed. */
} hvif_status;
* \typedef Opaque structure to reference a parsed image.
* An API to inspect the image will be provided later.
typedef struct hvif_image hvif_image;
* \typedef Captures the result of parsing: a status code together with the
* image.
typedef struct hvif_result hvif_result;
struct hvif_result
hvif_status status;
hvif_image* image;
hvif_status status; /**< Indicates success or an error in parsing. */
hvif_image* image; /**< The image structure. NULL if parsing failed. */
* \brief Parses a \a hvif image from a file
* \param[in] file A valid file handler
* \return A `hvif_result` structure. A status other then SUCCESS indicates
* an error. In this case the image is NULL. Otherwise the image needs
* to be freed. A success does not indicate that the image is renderable.
hvif_result hvif_from_file(FILE* file);
* \brief Frees the memory of the image datastructures.
* \param[in] image An image pointer returned by a previous call to
* `hvif_from_file`. Can be NULL.
void hvif_free(hvif_image* image);
#endif /* HVIF_LIGHT_H */