API documentation

Introduces API reference documentation. An AWK script is used to extract the
documentation from the hipack.h header, and generate reStructuredText which is
then processed by Sphinx.

Closes #3

.gitignore

@@ -3,7 +3,8 @@
 .*.sw[op]
 *.gcda
 *.gcno
-tools/hipack-cat
-tools/hipack-get
-tools/hipack-parse
-tools/hipack-roundtrip
+/tools/hipack-cat
+/tools/hipack-get
+/tools/hipack-parse
+/tools/hipack-roundtrip
+/doc/_build/

Makefile

@@ -49,4 +49,10 @@ ${hipack_PATH}/fpconv/src/fpconv.c: ${hipack_PATH}/.gitmodules
 	cd ${hipack_PATH} && git submodule update fpconv
 	touch $@
 
-.PHONY: hipack hipack-objs hipack-tools hipack-check
+${hipack_PATH}/doc/apiref.rst: ${hipack_PATH}/hipack.h ${hipack_PATH}/tools/extract-docs.awk
+	awk -f ${hipack_PATH}/tools/extract-docs.awk $< > $@
+
+doc: ${hipack_PATH}/doc/apiref.rst
+	${MAKE} -C ${hipack_PATH}/doc html
+
+.PHONY: hipack hipack-objs hipack-tools hipack-check doc

doc/Makefile

@@ -0,0 +1,192 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/hipack-c.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/hipack-c.qhc"
+
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/hipack-c"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/hipack-c"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

doc/apiref.rst

@@ -0,0 +1,528 @@
+
+
+
+=============
+API Reference
+=============
+
+Types
+=====
+
+.. c:type:: hipack_type_t
+
+
+   Type of a value. This enumeration takes one of the following values:
+
+   - ``HIPACK_INTEGER``: Integer value.
+   - ``HIPACK_FLOAT``: Floating point value.
+   - ``HIPACK_BOOL``: Boolean value.
+   - ``HIPACK_STRING``: String value.
+   - ``HIPACK_LIST``: List value.
+   - ``HIPACK_DICT``: Dictionary value.
+
+.. c:type:: hipack_value_t
+
+
+   Represent any valid HiPack value.
+
+   - :func:`hipack_value_type()` obtains the type of a value.
+
+.. c:type:: hipack_string_t
+
+
+   String value.
+
+.. c:type:: hipack_list_t
+
+
+   List value.
+
+.. c:type:: hipack_dict_t
+
+
+   Dictionary value.
+
+
+
+Memory Allocation
+=================
+
+How ``hipack-c`` allocates memory can be customized by setting
+:c:data:`hipack_alloc` to a custom allocation function.
+
+.. c:var:: hipack_alloc
+
+
+   Allocation function. By default it is set to :func:`hipack_alloc_stdlib()`,
+   which uses the implementations of ``malloc()``, ``realloc()``, and
+   ``free()`` provided by the C library.
+
+   Allocation functions always have the following prototype:
+
+   .. code-block:: c
+
+      void* func (void *oldptr, size_t size);
+
+   The behavior must be as follows:
+
+   - When invoked with ``oldptr`` set to ``NULL``, and a non-zero ``size``,
+     the function behaves like ``malloc()``: a memory block of at least
+     ``size`` bytes is allocated and a pointer to it returned.
+   - When ``oldptr`` is non-``NULL``, and a non-zero ``size``, the function
+     behaves like ``realloc()``: the memory area pointed to by ``oldptr``
+     is resized to be at least ``size`` bytes, or its contents moved to a
+     new memory area of at least ``size`` bytes. The returned pointer may
+     either be ``oldptr``, or a pointer to the new memory area if the data
+     was relocated.
+   - When ``oldptr`` is non-``NULL``, and ``size`` is zero, the function
+     behaves like ``free()``.
+
+.. c:function:: void* hipack_alloc_stdlib(void*, size_t)
+
+
+   Default allocation function. It uses ``malloc()``, ``realloc()``, and
+   ``free()`` from the C library. By default :any:`hipack_alloc` is set
+   to use this function.
+
+.. c:function:: void* hipack_alloc_array_extra (void *oldptr, size_t nmemb, size_t size, size_t extra)
+
+
+   Allocates (if `oldptr` is ``NULL``) or reallocates (if `oldptr` is
+   non-``NULL``) memory for an array which contains `nmemb` elements, each one
+   of `size` bytes, plus an arbitrary amount of `extra` bytes.
+
+   This function is used internally by the HiPack parser, and it is not likely
+   to be needed by client code.
+
+.. c:function:: void* hipack_alloc_array (void *optr, size_t nmemb, size_t size)
+
+
+   Same as :c:func:`hipack_alloc_array_extra()`, without allowing to specify
+   the amount of extra bytes. The following calls are both equivalent:
+
+   .. code-block:: c
+
+      void *a = hipack_alloc_array_extra (NULL, 10, 4, 0);
+      void *b = hipack_alloc_array (NULL, 10, 4);
+
+   See :c:func:`hipack_alloc_array_extra()` for details.
+
+.. c:function:: void* hipack_alloc_bzero (size_t size)
+
+
+   Allocates an area of memory of `size` bytes, and initializes it to zeroes.
+
+.. c:function:: void hipack_alloc_free (void *pointer)
+
+
+   Frees the memory area referenced by the given `pointer`.
+
+
+
+String Functions
+================
+
+The following functions are provided as a convenience to operate on values
+of type :c:type:`hipack_string_t`.
+
+.. note:: The hash function used by :c:func:`hipack_string_hash()` is
+   *not* guaranteed to be cryptographically safe. Please do avoid exposing
+   values returned by this function to the attack surface of your
+   applications, in particular *do not expose them to the network*.
+
+.. c:function:: hipack_string_t* hipack_string_copy (const hipack_string_t *hstr)
+
+
+   Returns a new copy of a string.
+
+   The returned value must be freed using :c:func:`hipack_string_free()`.
+
+.. c:function:: hipack_string_t* hipack_string_new_from_string (const char *str)
+
+
+   Creates a new string from a C-style zero terminated string.
+
+   The returned value must be freed using :c:func:`hipack_string_free()`.
+
+.. c:function:: hipack_string_t* hipack_string_new_from_lstring (const char *str, uint32_t len)
+
+
+   Creates a new string from a memory area and its length.
+
+   The returned value must be freed using :c:func:`hipack_string_free()`.
+
+.. c:function:: uint32_t hipack_string_hash (const hipack_string_t *hstr)
+
+
+   Calculates a hash value for a string.
+
+.. c:function:: bool hipack_string_equal (const hipack_string_t *hstr1, const hipack_string_t *hstr2)
+
+   Compares two strings to check whether their contents are the same.
+
+.. c:function:: void hipack_string_free (hipack_string_t *hstr)
+
+   Frees the memory used by a string.
+
+
+
+List Functions
+==============
+
+.. c:function:: hipack_list_t* hipack_list_new (uint32_t size)
+
+   Creates a new list for ``size`` elements.
+
+.. c:function:: void hipack_list_free (hipack_list_t *list)
+
+   Frees the memory used by a list.
+
+.. c:function:: bool hipack_list_equal (const hipack_list_t *a, const hipack_list_t *b)
+
+   Checks whether two lists contains the same values.
+
+.. c:function:: uint32_t hipack_list_size (const hipack_list_t *list)
+
+   Obtains the number of elements in a list.
+
+.. c:macro:: HIPACK_LIST_AT(list, index)
+
+
+   Obtains a pointer to the element at a given `index` of a `list`.
+
+
+
+Dictionary Functions
+====================
+
+.. c:function:: uint32_t hipack_dict_size (const hipack_dict_t *dict)
+
+
+   Obtains the number of elements in a dictionary.
+
+.. c:function:: hipack_dict_t* hipack_dict_new (void)
+
+
+   Creates a new, empty dictionary.
+
+.. c:function:: void hipack_dict_free (hipack_dict_t *dict)
+
+
+   Frees the memory used by a dictionary.
+
+.. c:function:: bool hipack_dict_equal (const hipack_dict_t *a, const hipack_dict_t *b)
+
+
+   Checks whether two dictinaries contain the same keys, and their associated
+   values in each of the dictionaries are equal.
+
+.. c:function:: void hipack_dict_set (hipack_dict_t *dict, const hipack_string_t *key, const hipack_value_t *value)
+
+
+   Adds an association of a `key` to a `value`.
+
+   Note that this function will copy the `key`. If you are not planning to
+   continue reusing the `key`, it is recommended to use
+   :c:func:`hipack_dict_set_adopt_key()` instead.
+
+.. c:function:: void hipack_dict_set_adopt_key (hipack_dict_t *dict, hipack_string_t **key, const hipack_value_t *value)
+
+
+   Adds an association of a `key` to a `value`, passing ownership of the
+   memory using by the `key` to the dictionary (i.e. the string used as key
+   will be freed by the dictionary).
+
+   Use this function instead of :c:func:`hipack_dict_set()` when the `key`
+   is not going to be used further afterwards.
+
+.. c:function:: void hipack_dict_del (hipack_dict_t *dict, const hipack_string_t *key)
+
+
+   Removes the element from a dictionary associated to a `key`.
+
+.. c:function:: hipack_value_t* hipack_dict_get (const hipack_dict_t *dict, const hipack_string_t *key)
+
+
+   Obtains the value associated to a `key` from a dictionary.
+
+   The returned value points to memory owned by the dictionary. The value can
+   be modified in-place, but it shall not be freed.
+
+.. c:function:: hipack_value_t* hipack_dict_first (const hipack_dict_t *dict, const hipack_string_t **key)
+
+
+   Obtains an a *(key, value)* pair, which is considered the *first* in
+   iteration order. This can be used in combination with
+   :c:func:`hipack_dict_next()` to enumerate all the *(key, value)* pairs
+   stored in the dictionary:
+
+   .. code-block:: c
+
+      hipack_dict_t *d = get_dictionary ();
+      hipack_value_t *v;
+      hipack_string_t *k;
+
+      for (v = hipack_dict_first (d, &k);
+           v != NULL;
+           v = hipack_dict_next (v, &k)) {
+          // Use "k" and "v" normally.
+      }
+
+   As a shorthand, consider using :c:macro:`HIPACK_DICT_FOREACH()` instead.
+
+.. c:function:: hipack_value_t* hipack_dict_next (hipack_value_t *value, const hipack_string_t **key)
+
+
+   Iterates to the next *(key, value)* pair of a dictionary. For usage
+   details, see :c:func:`hipack_dict_first()`.
+
+.. c:macro:: HIPACK_DICT_FOREACH(dict, key, value)
+
+
+   Convenience macro used to iterate over the *(key, value)* pairs contained
+   in a dictionary. Internally this uses :c:func:`hipack_dict_first()` and
+   :c:func:`hipack_dict_next()`.
+
+   .. code-block:: c
+
+      hipack_dict_t *d = get_dictionary ();
+      hipack_string_t *k;
+      hipack_value_t *v;
+      HIPACK_DICT_FOREACH (d, k, v) {
+          // Use "k" and "v"
+      }
+
+   Using this macro is the recommended way of writing a loop to enumerate
+   elements from a dictionary.
+
+
+
+Value Functions
+===============
+
+.. c:function:: hipack_type_t hipack_value_type (const hipack_value_t *value)
+
+
+   Obtains the type of a value.
+
+.. c:function:: bool hipack_value_is_integer (const hipack_value_t *value)
+
+   Checks whether a value is an integer.
+
+.. c:function:: bool hipack_value_is_float (const hipack_value_t *value)
+
+   Checks whether a value is a floating point number.
+
+.. c:function:: bool hipack_value_is_bool (const hipack_value_t *value)
+
+   Checks whether a value is a boolean.
+
+.. c:function:: bool hipack_value_is_string (const hipack_value_t *value)
+
+   Checks whether a value is a string.
+
+.. c:function:: bool hipack_value_is_list (const hipack_value_t *value)
+
+   Checks whether a value is a list.
+
+.. c:function:: bool hipack_value_is_dict (const hipack_value_t *value)
+
+   Checks whether a value is a dictionary.
+
+.. c:function:: const int32_t hipack_value_get_integer (const hipack_value_t *value)
+
+   Obtains a numeric value as an ``int32_t``.
+
+.. c:function:: const double hipack_value_get_float (const hipack_value_t *value)
+
+   Obtains a floating point value as a ``double``.
+
+.. c:function:: const bool hipack_value_get_bool (const hipack_value_t *value)
+
+   Obtains a boolean value as a ``bool``.
+
+.. c:function:: const hipack_string_t* hipack_value_get_string (const hipack_value_t *value)
+
+   Obtains a numeric value as a :c:type:`hipack_string_t`.
+
+.. c:function:: const hipack_list_t* hipack_value_get_list (const hipack_value_t *value)
+
+   Obtains a numeric value as a :c:type:`hipack_list_t`.
+
+.. c:function:: const hipack_dict_t* hipack_value_get_dict (const hipack_value_t *value)
+
+   Obtains a numeric value as a :c:type:`hipack_dict_t`.
+
+.. c:function:: bool hipack_value_equal (const hipack_value_t *a, const hipack_value_t *b)
+
+
+   Checks whether two values are equal.
+
+.. c:function:: void hipack_value_free (hipack_value_t *value)
+
+
+   Frees the memory used by a value.
+
+.. c:function:: void hipack_value_add_annot (hipack_value_t *value, const char *annot)
+
+
+   Adds an annotation to a value. If the value already had the annotation,
+   this function is a no-op.
+
+.. c:function:: bool hipack_value_has_annot (const hipack_value_t *value, const char *annot)
+
+
+   Checks whether a value has a given annotation.
+
+.. c:function:: void hipack_value_del_annot (hipack_value_t *value, const char *annot)
+
+
+   Removes an annotation from a value. If the annotation was not present, this
+   function is a no-op.
+
+
+
+Reader Interface
+================
+
+.. c:type:: hipack_reader_t
+
+
+   Allows communicating with the parser, instructing it how to read text
+   input data, and provides a way for the parser to report errors back.
+
+   The following members of the structure are to be used by client code:
+
+   .. c:member:: int (*getchar)(void *data)
+
+      Reader callback function. The function will be called every time the
+      next character of input is needed. It must return it as an integer,
+      :any:`HIPACK_IO_EOF` when trying to read pas the end of the input,
+      or :any:`HIPACK_IO_ERROR` if an input error occurs.
+
+
+   .. c:member:: const char *error
+
+      On error, a string describing the issue, suitable to be displayed to
+      the user.
+
+   .. c:member:: unsigned error_line
+
+      On error, the line number where parsing was stopped.
+
+   .. c:member:: unsigned error_column
+
+      On error, the column where parsing was stopped.
+
+.. c:macro:: HIPACK_IO_EOF
+
+   Constant returned by reader functions when trying to read past the end of
+   the input.
+
+.. c:macro:: HIPACK_IO_ERROR
+
+   Constant returned by reader functions on input errors.
+
+.. c:macro:: HIPACK_READ_ERROR
+
+
+   Constant value used to signal an underlying input error.
+
+   The `error` field of :c:type:`hipack_reader_t` is set to this value when
+   the reader function returns :any:`HIPACK_IO_ERROR`. This is provided to
+   allow client code to detect this condition and further query for the
+   nature of the input error.
+
+.. c:function:: hipack_dict_t* hipack_read (hipack_reader_t *reader)
+
+
+   Reads a HiPack message from a stream `reader` and returns a dictionary.
+
+   On error, ``NULL`` is returned, and the members `error`, `error_line`,
+   and `error_column` (see :c:type:`hipack_reader_t`) are set accordingly
+   in the `reader`.
+
+.. c:function:: int hipack_stdio_getchar (void* fp)
+
+
+   Reader function which uses ``FILE*`` objects from the standard C library.
+
+   To use this function to read from a ``FILE*``, first open a file, and
+   then create a reader using this function and the open file as data to
+   be passed to it, and then use :c:func:`hipack_read()`:
+
+   .. code-block:: c
+
+      FILE* stream = fopen (HIPACK_FILE_PATH, "rb")
+      hipack_reader_t reader = {
+          .getchar = hipack_stdio_getchar,
+          .getchar_data = stream,
+      };
+      hipack_dict_t *message = hipack_read (&reader);
+
+   The user is responsible for closing the ``FILE*`` after using it.
+
+
+
+Writer Interface
+================
+
+.. c:type:: hipack_writer_t
+
+
+   Allows specifying how to write text output data, and configuring how
+   the produced HiPack output looks like.
+
+   The following members of the structure are to be used by client code:
+
+   .. c:member:: int (*putchar)(void *data, int ch)
+
+      Writer callback function. The function will be called every time a
+      character is produced as output. It must return :any:`HIPACK_IO_ERROR`
+      if an output error occurs, and it is invalid for the callback to
+      return :any:`HIPACK_IO_EOF`. Any other value is interpreted as
+      indication of success.
+
+   .. c:member:: void* putchar_data
+
+      Data passed to the writer callback function.
+
+   .. c:member:: int32_t indent
+
+      Either :any:`HIPACK_WRITER_COMPACT` or :any:`HIPACK_WRITER_INDENTED`.
+
+.. c:macro:: HIPACK_WRITER_COMPACT
+
+   Flag to generate output HiPack messages in their compact representation.
+
+.. c:macro:: HIPACK_WRITER_INDENTED
+
+   Flag to generate output HiPack messages in “indented” (pretty-printed)
+   representation.
+
+.. c:function:: bool hipack_write (hipack_writer_t *writer, const hipack_dict_t *message)
+
+
+   Writes a HiPack `message` to a stream `writer`, and returns whether writing
+   the message was successful.
+
+.. c:function:: int hipack_stdio_putchar (void* data, int ch)
+
+
+   Writer function which uses ``FILE*`` objects from the standard C library.
+
+   To use this function to write a message to a ``FILE*``, first open a file,
+   then create a writer using this function, and then use
+   :c:func:`hipack_write()`:
+
+   .. code-block:: c
+
+      FILE* stream = fopen (HIPACK_FILE_PATH, "wb");
+      hipack_writer_t writer = {
+          .putchar = hipack_stdio_putchar,
+          .putchar_data = stream,
+      };
+      hipack_write (&writer, message);
+
+   The user is responsible for closing the ``FILE*`` after using it.
+

doc/conf.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# hipack-c documentation build configuration file, created by
+# sphinx-quickstart on Thu Dec 17 20:03:40 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import shlex
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'hipack-c'
+copyright = '2015, Adrian Perez de Castro'
+author = 'Adrian Perez de Castro'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.2.0'
+# The full version, including alpha/beta/rc tags.
+release = '0.2.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'hipack-cdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  (master_doc, 'hipack-c.tex', 'hipack-c Documentation',
+   'Adrian Perez de Castro', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'hipack-c', 'hipack-c Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  (master_doc, 'hipack-c', 'hipack-c Documentation',
+   author, 'hipack-c', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False

doc/index.rst

@@ -0,0 +1,24 @@
+.. hipack-c documentation master file, created by
+   sphinx-quickstart on Thu Dec 17 20:03:40 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to hipack-c's documentation!
+====================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart
+   apiref
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/make.bat

@@ -0,0 +1,263 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	echo.  coverage   to run coverage check of the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 1>NUL 2>NUL
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\hipack-c.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\hipack-c.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "coverage" (
+	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

doc/quickstart.rst

@@ -0,0 +1,22 @@
+==========
+Quickstart
+==========
+
+This guide will walk you through the usage of the ``hipack-c`` C library.
+
+
+Reading (deserialization)
+=========================
+
+
+Writing (serialization)
+=======================
+
+
+Values
+======
+
+
+Annotations
+===========
+

hipack.h

@@ -14,7 +14,26 @@
 #include <string.h>
 #include <stdbool.h>
 
+/**
+ * =============
+ * API Reference
+ * =============
+ *
+ * Types
+ * =====
+ */
 
+/*~t hipack_type_t
+ *
+ * Type of a value. This enumeration takes one of the following values:
+ *
+ * - ``HIPACK_INTEGER``: Integer value.
+ * - ``HIPACK_FLOAT``: Floating point value.
+ * - ``HIPACK_BOOL``: Boolean value.
+ * - ``HIPACK_STRING``: String value.
+ * - ``HIPACK_LIST``: List value.
+ * - ``HIPACK_DICT``: Dictionary value.
+ */
 typedef enum {
     HIPACK_INTEGER,
     HIPACK_FLOAT,
@@ -25,33 +44,6 @@ typedef enum {
 } hipack_type_t;
 
 
-extern void* (*hipack_alloc) (void*, size_t);
-extern void* hipack_alloc_stdlib (void*, size_t);
-extern void* hipack_alloc_array_extra (void*, size_t nmemb, size_t size, size_t extra);
-
-
-static inline void*
-hipack_alloc_bzero (size_t size)
-{
-    assert (size > 0);
-    return memset ((*hipack_alloc) (NULL, size), 0, size);
-}
-
-
-static inline void*
-hipack_alloc_array (void *optr, size_t nmemb, size_t size)
-{
-    return hipack_alloc_array_extra (optr, nmemb, size, 0);
-}
-
-
-static inline void
-hipack_alloc_free (void *optr)
-{
-    (*hipack_alloc) (optr, 0);
-}
-
-
 /* Forward declarations. */
 typedef struct hipack_value     hipack_value_t;
 typedef struct hipack_string    hipack_string_t;
@@ -60,6 +52,12 @@ typedef struct hipack_dict_node hipack_dict_node_t;
 typedef struct hipack_list      hipack_list_t;
 
 
+/*~t hipack_value_t
+ *
+ * Represent any valid HiPack value.
+ *
+ * - :func:`hipack_value_type()` obtains the type of a value.
+ */
 struct hipack_value {
     hipack_type_t  type;
     hipack_dict_t *annot;
@@ -74,32 +72,210 @@ struct hipack_value {
 };
 
 
+/*~t hipack_string_t
+ *
+ * String value.
+ */
 struct hipack_string {
     uint32_t size;
     uint8_t  data[]; /* C99 flexible array. */
 };
 
+/*~t hipack_list_t
+ *
+ * List value.
+ */
+struct hipack_list {
+    uint32_t       size;
+    hipack_value_t data[]; /* C99 flexible array. */
+};
+
+/*~t hipack_dict_t
+ *
+ * Dictionary value.
+ */
+struct hipack_dict {
+    hipack_dict_node_t **nodes;
+    hipack_dict_node_t  *first;
+    uint32_t             count;
+    uint32_t             size;
+};
+
+
+/**
+ * Memory Allocation
+ * =================
+ *
+ * How ``hipack-c`` allocates memory can be customized by setting
+ * :c:data:`hipack_alloc` to a custom allocation function.
+ */
+
+/*~v hipack_alloc
+ *
+ * Allocation function. By default it is set to :func:`hipack_alloc_stdlib()`,
+ * which uses the implementations of ``malloc()``, ``realloc()``, and
+ * ``free()`` provided by the C library.
+ *
+ * Allocation functions always have the following prototype:
+ *
+ * .. code-block:: c
+ *
+ *    void* func (void *oldptr, size_t size);
+ *
+ * The behavior must be as follows:
+ *
+ * - When invoked with ``oldptr`` set to ``NULL``, and a non-zero ``size``,
+ *   the function behaves like ``malloc()``: a memory block of at least
+ *   ``size`` bytes is allocated and a pointer to it returned.
+ * - When ``oldptr`` is non-``NULL``, and a non-zero ``size``, the function
+ *   behaves like ``realloc()``: the memory area pointed to by ``oldptr``
+ *   is resized to be at least ``size`` bytes, or its contents moved to a
+ *   new memory area of at least ``size`` bytes. The returned pointer may
+ *   either be ``oldptr``, or a pointer to the new memory area if the data
+ *   was relocated.
+ * - When ``oldptr`` is non-``NULL``, and ``size`` is zero, the function
+ *   behaves like ``free()``.
+ */
+extern void* (*hipack_alloc) (void*, size_t);
+
+/*~f void* hipack_alloc_stdlib(void*, size_t)
+ *
+ * Default allocation function. It uses ``malloc()``, ``realloc()``, and
+ * ``free()`` from the C library. By default :any:`hipack_alloc` is set
+ * to use this function.
+ */
+extern void* hipack_alloc_stdlib (void*, size_t);
+
+/*~f void* hipack_alloc_array_extra (void *oldptr, size_t nmemb, size_t size, size_t extra)
+ *
+ * Allocates (if `oldptr` is ``NULL``) or reallocates (if `oldptr` is
+ * non-``NULL``) memory for an array which contains `nmemb` elements, each one
+ * of `size` bytes, plus an arbitrary amount of `extra` bytes.
+ *
+ * This function is used internally by the HiPack parser, and it is not likely
+ * to be needed by client code.
+ */
+extern void* hipack_alloc_array_extra (void*, size_t nmemb, size_t size, size_t extra);
+
+/*~f void* hipack_alloc_array (void *optr, size_t nmemb, size_t size)
+ *
+ * Same as :c:func:`hipack_alloc_array_extra()`, without allowing to specify
+ * the amount of extra bytes. The following calls are both equivalent:
+ *
+ * .. code-block:: c
+ *
+ *    void *a = hipack_alloc_array_extra (NULL, 10, 4, 0);
+ *    void *b = hipack_alloc_array (NULL, 10, 4);
+ *
+ * See :c:func:`hipack_alloc_array_extra()` for details.
+ */
+static inline void*
+hipack_alloc_array (void *optr, size_t nmemb, size_t size)
+{
+    return hipack_alloc_array_extra (optr, nmemb, size, 0);
+}
+
+/*~f void* hipack_alloc_bzero (size_t size)
+ *
+ * Allocates an area of memory of `size` bytes, and initializes it to zeroes.
+ */
+static inline void*
+hipack_alloc_bzero (size_t size)
+{
+    assert (size > 0);
+    return memset ((*hipack_alloc) (NULL, size), 0, size);
+}
+
+/*~f void hipack_alloc_free (void *pointer)
+ *
+ * Frees the memory area referenced by the given `pointer`.
+ */
+static inline void
+hipack_alloc_free (void *optr)
+{
+    (*hipack_alloc) (optr, 0);
+}
 
+
+/**
+ * String Functions
+ * ================
+ *
+ * The following functions are provided as a convenience to operate on values
+ * of type :c:type:`hipack_string_t`.
+ *
+ * .. note:: The hash function used by :c:func:`hipack_string_hash()` is
+ *    *not* guaranteed to be cryptographically safe. Please do avoid exposing
+ *    values returned by this function to the attack surface of your
+ *    applications, in particular *do not expose them to the network*.
+ */
+
+/*~f hipack_string_t* hipack_string_copy (const hipack_string_t *hstr)
+ *
+ * Returns a new copy of a string.
+ *
+ * The returned value must be freed using :c:func:`hipack_string_free()`.
+ */
 extern hipack_string_t* hipack_string_copy (const hipack_string_t *hstr);
+
+/*~f hipack_string_t* hipack_string_new_from_string (const char *str)
+ *
+ * Creates a new string from a C-style zero terminated string.
+ *
+ * The returned value must be freed using :c:func:`hipack_string_free()`.
+ */
 extern hipack_string_t* hipack_string_new_from_string (const char *str);
+
+/*~f hipack_string_t* hipack_string_new_from_lstring (const char *str, uint32_t len)
+ *
+ * Creates a new string from a memory area and its length.
+ *
+ * The returned value must be freed using :c:func:`hipack_string_free()`.
+ */
 extern hipack_string_t* hipack_string_new_from_lstring (const char *str, uint32_t len);
+
+/*~f uint32_t hipack_string_hash (const hipack_string_t *hstr)
+ *
+ * Calculates a hash value for a string.
+ */
 extern uint32_t hipack_string_hash (const hipack_string_t *hstr);
+
+/*~f bool hipack_string_equal (const hipack_string_t *hstr1, const hipack_string_t *hstr2)
+ * Compares two strings to check whether their contents are the same.
+ */
 extern bool hipack_string_equal (const hipack_string_t *hstr1,
                                  const hipack_string_t *hstr2);
-extern void hipack_string_free (hipack_string_t *hstr);
 
+/*~f void hipack_string_free (hipack_string_t *hstr)
+ * Frees the memory used by a string.
+ */
+extern void hipack_string_free (hipack_string_t *hstr);
 
-struct hipack_list {
-    uint32_t       size;
-    hipack_value_t data[]; /* C99 flexible array. */
-};
 
+/**
+ * List Functions
+ * ==============
+ */
 
+/*~f hipack_list_t* hipack_list_new (uint32_t size)
+ * Creates a new list for ``size`` elements.
+ */
 extern hipack_list_t* hipack_list_new (uint32_t size);
+
+/*~f void hipack_list_free (hipack_list_t *list)
+ * Frees the memory used by a list.
+ */
 extern void hipack_list_free (hipack_list_t *list);
+
+/*~f bool hipack_list_equal (const hipack_list_t *a, const hipack_list_t *b)
+ * Checks whether two lists contains the same values.
+ */
 extern bool hipack_list_equal (const hipack_list_t *a,
                                const hipack_list_t *b);
 
+/*~f uint32_t hipack_list_size (const hipack_list_t *list)
+ * Obtains the number of elements in a list.
+ */
 static inline uint32_t
 hipack_list_size (const hipack_list_t *list)
 {
@@ -107,18 +283,23 @@ hipack_list_size (const hipack_list_t *list)
     return list->size;
 }
 
+/*~M HIPACK_LIST_AT(list, index)
+ *
+ * Obtains a pointer to the element at a given `index` of a `list`.
+ */
 #define HIPACK_LIST_AT(_list, _index) \
     (assert ((_index) < (_list)->size), &((_list)->data[_index]))
 
 
-struct hipack_dict {
-    hipack_dict_node_t **nodes;
-    hipack_dict_node_t  *first;
-    uint32_t             count;
-    uint32_t             size;
-};
-
+/**
+ * Dictionary Functions
+ * ====================
+ */
 
+/*~f uint32_t hipack_dict_size (const hipack_dict_t *dict)
+ *
+ * Obtains the number of elements in a dictionary.
+ */
 static inline uint32_t
 hipack_dict_size (const hipack_dict_t *dict)
 {
@@ -126,45 +307,175 @@ hipack_dict_size (const hipack_dict_t *dict)
     return dict->count;
 }
 
-
+/*~f hipack_dict_t* hipack_dict_new (void)
+ *
+ * Creates a new, empty dictionary.
+ */
 extern hipack_dict_t* hipack_dict_new (void);
+
+/*~f void hipack_dict_free (hipack_dict_t *dict)
+ *
+ * Frees the memory used by a dictionary.
+ */
 extern void hipack_dict_free (hipack_dict_t *dict);
 
+/*~f bool hipack_dict_equal (const hipack_dict_t *a, const hipack_dict_t *b)
+ *
+ * Checks whether two dictinaries contain the same keys, and their associated
+ * values in each of the dictionaries are equal.
+ */
 extern bool hipack_dict_equal (const hipack_dict_t *a,
                                const hipack_dict_t *b);
 
+/*~f void hipack_dict_set (hipack_dict_t *dict, const hipack_string_t *key, const hipack_value_t *value)
+ *
+ * Adds an association of a `key` to a `value`.
+ *
+ * Note that this function will copy the `key`. If you are not planning to
+ * continue reusing the `key`, it is recommended to use
+ * :c:func:`hipack_dict_set_adopt_key()` instead.
+ */
+extern void hipack_dict_set (hipack_dict_t         *dict,
+                             const hipack_string_t *key,
+                             const hipack_value_t  *value);
 
+/*~f void hipack_dict_set_adopt_key (hipack_dict_t *dict, hipack_string_t **key, const hipack_value_t *value)
+ *
+ * Adds an association of a `key` to a `value`, passing ownership of the
+ * memory using by the `key` to the dictionary (i.e. the string used as key
+ * will be freed by the dictionary).
+ *
+ * Use this function instead of :c:func:`hipack_dict_set()` when the `key`
+ * is not going to be used further afterwards.
+ */
 extern void hipack_dict_set_adopt_key (hipack_dict_t        *dict,
                                        hipack_string_t     **key,
                                        const hipack_value_t *value);
 
-extern void hipack_dict_set (hipack_dict_t         *dict,
-                             const hipack_string_t *key,
-                             const hipack_value_t  *value);
-
+/*~f void hipack_dict_del (hipack_dict_t *dict, const hipack_string_t *key)
+ *
+ * Removes the element from a dictionary associated to a `key`.
+ */
 extern void hipack_dict_del (hipack_dict_t         *dict,
                              const hipack_string_t *key);
 
+/*~f hipack_value_t* hipack_dict_get (const hipack_dict_t *dict, const hipack_string_t *key)
+ *
+ * Obtains the value associated to a `key` from a dictionary.
+ *
+ * The returned value points to memory owned by the dictionary. The value can
+ * be modified in-place, but it shall not be freed.
+ */
 extern hipack_value_t* hipack_dict_get (const hipack_dict_t   *dict,
                                         const hipack_string_t *key);
 
+/*~f hipack_value_t* hipack_dict_first (const hipack_dict_t *dict, const hipack_string_t **key)
+ *
+ * Obtains an a *(key, value)* pair, which is considered the *first* in
+ * iteration order. This can be used in combination with
+ * :c:func:`hipack_dict_next()` to enumerate all the *(key, value)* pairs
+ * stored in the dictionary:
+ *
+ * .. code-block:: c
+ *
+ *    hipack_dict_t *d = get_dictionary ();
+ *    hipack_value_t *v;
+ *    hipack_string_t *k;
+ *
+ *    for (v = hipack_dict_first (d, &k);
+ *         v != NULL;
+ *         v = hipack_dict_next (v, &k)) {
+ *        // Use "k" and "v" normally.
+ *    }
+ *
+ * As a shorthand, consider using :c:macro:`HIPACK_DICT_FOREACH()` instead.
+ */
 extern hipack_value_t* hipack_dict_first (const hipack_dict_t    *dict,
                                           const hipack_string_t **key);
 
+/*~f hipack_value_t* hipack_dict_next (hipack_value_t *value, const hipack_string_t **key)
+ *
+ * Iterates to the next *(key, value)* pair of a dictionary. For usage
+ * details, see :c:func:`hipack_dict_first()`.
+ */
 extern hipack_value_t* hipack_dict_next (hipack_value_t         *value,
                                          const hipack_string_t **key);
 
+/*~M HIPACK_DICT_FOREACH(dict, key, value)
+ *
+ * Convenience macro used to iterate over the *(key, value)* pairs contained
+ * in a dictionary. Internally this uses :c:func:`hipack_dict_first()` and
+ * :c:func:`hipack_dict_next()`.
+ *
+ * .. code-block:: c
+ *
+ *    hipack_dict_t *d = get_dictionary ();
+ *    hipack_string_t *k;
+ *    hipack_value_t *v;
+ *    HIPACK_DICT_FOREACH (d, k, v) {
+ *        // Use "k" and "v"
+ *    }
+ *
+ * Using this macro is the recommended way of writing a loop to enumerate
+ * elements from a dictionary.
+ */
 #define HIPACK_DICT_FOREACH(_d, _k, _v)          \
     for ((_v) = hipack_dict_first ((_d), &(_k)); \
          (_v) != NULL;                           \
          (_v) = hipack_dict_next ((_v), &(_k)))
 
+/**
+ * Value Functions
+ * ===============
+ */
+
+/*~f hipack_type_t hipack_value_type (const hipack_value_t *value)
+ *
+ * Obtains the type of a value.
+ */
 static inline hipack_type_t
 hipack_value_type (const hipack_value_t *value)
 {
     return value->type;
 }
 
+/*~f bool hipack_value_is_integer (const hipack_value_t *value)
+ * Checks whether a value is an integer.
+ */
+/*~f bool hipack_value_is_float (const hipack_value_t *value)
+ * Checks whether a value is a floating point number.
+ */
+/*~f bool hipack_value_is_bool (const hipack_value_t *value)
+ * Checks whether a value is a boolean.
+ */
+/*~f bool hipack_value_is_string (const hipack_value_t *value)
+ * Checks whether a value is a string.
+ */
+/*~f bool hipack_value_is_list (const hipack_value_t *value)
+ * Checks whether a value is a list.
+ */
+/*~f bool hipack_value_is_dict (const hipack_value_t *value)
+ * Checks whether a value is a dictionary.
+ */
+
+/*~f const int32_t hipack_value_get_integer (const hipack_value_t *value)
+ * Obtains a numeric value as an ``int32_t``.
+ */
+/*~f const double hipack_value_get_float (const hipack_value_t *value)
+ * Obtains a floating point value as a ``double``.
+ */
+/*~f const bool hipack_value_get_bool (const hipack_value_t *value)
+ * Obtains a boolean value as a ``bool``.
+ */
+/*~f const hipack_string_t* hipack_value_get_string (const hipack_value_t *value)
+ * Obtains a numeric value as a :c:type:`hipack_string_t`.
+ */
+/*~f const hipack_list_t* hipack_value_get_list (const hipack_value_t *value)
+ * Obtains a numeric value as a :c:type:`hipack_list_t`.
+ */
+/*~f const hipack_dict_t* hipack_value_get_dict (const hipack_value_t *value)
+ * Obtains a numeric value as a :c:type:`hipack_dict_t`.
+ */
 
 #define HIPACK_TYPES(F) \
     F (int32_t,          integer, HIPACK_INTEGER) \
@@ -193,9 +504,18 @@ HIPACK_TYPES (HIPACK_DEFINE_GET_VALUE)
 #undef HIPACK_DEFINE_IS_TYPE
 #undef HIPACK_DEFINE_GET_VALUE
 
+
+/*~f bool hipack_value_equal (const hipack_value_t *a, const hipack_value_t *b)
+ *
+ * Checks whether two values are equal.
+ */
 extern bool hipack_value_equal (const hipack_value_t *a,
                                 const hipack_value_t *b);
 
+/*~f void hipack_value_free (hipack_value_t *value)
+ *
+ * Frees the memory used by a value.
+ */
 static inline void
 hipack_value_free (hipack_value_t *value)
 {
@@ -225,7 +545,11 @@ hipack_value_free (hipack_value_t *value)
     }
 }
 
-
+/*~f void hipack_value_add_annot (hipack_value_t *value, const char *annot)
+ *
+ * Adds an annotation to a value. If the value already had the annotation,
+ * this function is a no-op.
+ */
 static inline void
 hipack_value_add_annot (hipack_value_t *value,
                         const char     *annot)
@@ -245,6 +569,10 @@ hipack_value_add_annot (hipack_value_t *value,
     hipack_dict_set_adopt_key (value->annot, &key, &bool_true);
 }
 
+/*~f bool hipack_value_has_annot (const hipack_value_t *value, const char *annot)
+ *
+ * Checks whether a value has a given annotation.
+ */
 static inline bool
 hipack_value_has_annot (const hipack_value_t *value,
                         const char           *annot)
@@ -259,6 +587,11 @@ hipack_value_has_annot (const hipack_value_t *value,
     return result;
 }
 
+/*~f void hipack_value_del_annot (hipack_value_t *value, const char *annot)
+ *
+ * Removes an annotation from a value. If the annotation was not present, this
+ * function is a no-op.
+ */
 static inline void
 hipack_value_del_annot (hipack_value_t *value,
                         const char     *annot)
@@ -273,39 +606,152 @@ hipack_value_del_annot (hipack_value_t *value,
 }
 
 
+/**
+ * Reader Interface
+ * ================
+ */
+
+/*~t hipack_reader_t
+ *
+ * Allows communicating with the parser, instructing it how to read text
+ * input data, and provides a way for the parser to report errors back.
+ *
+ * The following members of the structure are to be used by client code:
+ */
 typedef struct {
-    int       (*getchar) (void*);
-    void       *getchar_data;
+    /*~m int (*getchar)(void *data)
+     * Reader callback function. The function will be called every time the
+     * next character of input is needed. It must return it as an integer,
+     * :any:`HIPACK_IO_EOF` when trying to read pas the end of the input,
+     * or :any:`HIPACK_IO_ERROR` if an input error occurs.
+     */
+    int (*getchar) (void*);
+
+    /*m void *getchar_data
+     * Data passed to the reader callback function.
+     */
+    void *getchar_data;
+
+    /*~m const char *error
+     * On error, a string describing the issue, suitable to be displayed to
+     * the user.
+     */
     const char *error;
-    unsigned    error_line;
-    unsigned    error_column;
+
+    /*~m unsigned error_line
+     * On error, the line number where parsing was stopped.
+     */
+    unsigned error_line;
+
+    /*~m unsigned error_column
+     * On error, the column where parsing was stopped.
+     */
+    unsigned error_column;
 } hipack_reader_t;
 
 
 enum {
+/*~M HIPACK_IO_EOF
+ * Constant returned by reader functions when trying to read past the end of
+ * the input.
+ */
     HIPACK_IO_EOF   = -1,
+
+/*~M HIPACK_IO_ERROR
+ * Constant returned by reader functions on input errors.
+ */
     HIPACK_IO_ERROR = -2,
 };
 
+/*~M HIPACK_READ_ERROR
+ *
+ * Constant value used to signal an underlying input error.
+ *
+ * The `error` field of :c:type:`hipack_reader_t` is set to this value when
+ * the reader function returns :any:`HIPACK_IO_ERROR`. This is provided to
+ * allow client code to detect this condition and further query for the
+ * nature of the input error.
+ */
 extern const char* HIPACK_READ_ERROR;
 
+/*~f hipack_dict_t* hipack_read (hipack_reader_t *reader)
+ *
+ * Reads a HiPack message from a stream `reader` and returns a dictionary.
+ *
+ * On error, ``NULL`` is returned, and the members `error`, `error_line`,
+ * and `error_column` (see :c:type:`hipack_reader_t`) are set accordingly
+ * in the `reader`.
+ */
+extern hipack_dict_t* hipack_read (hipack_reader_t *reader);
 
+/*~f int hipack_stdio_getchar (void* fp)
+ *
+ * Reader function which uses ``FILE*`` objects from the standard C library.
+ *
+ * To use this function to read from a ``FILE*``, first open a file, and
+ * then create a reader using this function and the open file as data to
+ * be passed to it, and then use :c:func:`hipack_read()`:
+ *
+ * .. code-block:: c
+ *
+ *    FILE* stream = fopen (HIPACK_FILE_PATH, "rb")
+ *    hipack_reader_t reader = {
+ *        .getchar = hipack_stdio_getchar,
+ *        .getchar_data = stream,
+ *    };
+ *    hipack_dict_t *message = hipack_read (&reader);
+ *
+ * The user is responsible for closing the ``FILE*`` after using it.
+ */
 extern int hipack_stdio_getchar (void* fp);
-extern hipack_dict_t* hipack_read (hipack_reader_t *reader);
 
 
-enum {
-    HIPACK_WRITER_COMPACT = -1,
-    HIPACK_WRITER_INDENTED = 0,
-};
+/**
+ * Writer Interface
+ * ================
+ */
 
+/*~t hipack_writer_t
+ *
+ * Allows specifying how to write text output data, and configuring how
+ * the produced HiPack output looks like.
+ *
+ * The following members of the structure are to be used by client code:
+ */
 typedef struct {
-    int   (*putchar) (void*, int);
-    void   *putchar_data;
+    /*~m int (*putchar)(void *data, int ch)
+     * Writer callback function. The function will be called every time a
+     * character is produced as output. It must return :any:`HIPACK_IO_ERROR`
+     * if an output error occurs, and it is invalid for the callback to
+     * return :any:`HIPACK_IO_EOF`. Any other value is interpreted as
+     * indication of success.
+     */
+    int (*putchar) (void*, int);
+
+    /*~m void* putchar_data
+     * Data passed to the writer callback function.
+     */
+    void *putchar_data;
+
+    /*~m int32_t indent
+     * Either :any:`HIPACK_WRITER_COMPACT` or :any:`HIPACK_WRITER_INDENTED`.
+     */
     int32_t indent;
 } hipack_writer_t;
 
 
+enum {
+/*~M HIPACK_WRITER_COMPACT
+ * Flag to generate output HiPack messages in their compact representation.
+ */
+    HIPACK_WRITER_COMPACT = -1,
+/*~M HIPACK_WRITER_INDENTED
+ * Flag to generate output HiPack messages in “indented” (pretty-printed)
+ * representation.
+ */
+    HIPACK_WRITER_INDENTED = 0,
+};
+
 #define HIPACK_DEFINE_WRITE_VALUE(_type, name, type_tag) \
     extern bool hipack_write_ ## name (hipack_writer_t *writer, \
                                        const _type value);
@@ -317,9 +763,33 @@ HIPACK_TYPES (HIPACK_DEFINE_WRITE_VALUE)
 extern bool hipack_write_value (hipack_writer_t      *writer,
                                 const hipack_value_t *value);
 
+/*~f bool hipack_write (hipack_writer_t *writer, const hipack_dict_t *message)
+ *
+ * Writes a HiPack `message` to a stream `writer`, and returns whether writing
+ * the message was successful.
+ */
 extern bool hipack_write (hipack_writer_t     *writer,
                           const hipack_dict_t *message);
 
+/*~f int hipack_stdio_putchar (void* data, int ch)
+ *
+ * Writer function which uses ``FILE*`` objects from the standard C library.
+ *
+ * To use this function to write a message to a ``FILE*``, first open a file,
+ * then create a writer using this function, and then use
+ * :c:func:`hipack_write()`:
+ *
+ * .. code-block:: c
+ *
+ *    FILE* stream = fopen (HIPACK_FILE_PATH, "wb");
+ *    hipack_writer_t writer = {
+ *        .putchar = hipack_stdio_putchar,
+ *        .putchar_data = stream,
+ *    };
+ *    hipack_write (&writer, message);
+ *
+ * The user is responsible for closing the ``FILE*`` after using it.
+ */
 extern int hipack_stdio_putchar (void* fp, int ch);
 
 #endif /* !HIPACK_H */

tools/extract-docs.awk

@@ -0,0 +1,57 @@
+BEGIN {
+	OBJ_MAP["f"] = "function";
+	OBJ_MAP["m"] = "member";
+	OBJ_MAP["M"] = "macro";
+	OBJ_MAP["t"] = "type";
+	OBJ_MAP["v"] = "var";
+	in_doc = 0;
+	indent = 0;
+}
+
+/^[[:space:]]*\/\*[\*\~][fmMtv]?/ {
+	if (!in_doc) {
+		in_doc = 1;
+	}
+
+	objtype = substr($1, length($1));
+	if (objtype in OBJ_MAP) {
+		objtype = OBJ_MAP[objtype];
+		indent = (index($0, "/") - 1);
+		if (indent) {
+			indent = indent / 4;
+		}
+		indent++;
+	} else {
+		indent = 0;
+		objtype = "";
+	}
+
+	if (length(objtype)) {
+		for (i = 1; i < indent; i++) printf("   ");
+		printf(".. c:%s::", objtype);
+		for (i = 2; i <= NF; i++) printf(" %s", $(i));
+	}
+	printf("\n\n");
+	next;
+}
+
+/^[[:space:]]*\*\// {
+	in_doc = 0;
+	printf("\n");
+	next;
+}
+
+/^[[:space:]]*\*[[:space:]]*$/ {
+	if (in_doc) print "";
+	next;
+}
+
+{
+	if (in_doc != 0) {
+		gsub(/^[[:space:]]*\*[[:space:]]/, "");
+		if (indent) {
+			for (i = 0; i < indent; i++) printf("   ");
+		}
+		print;
+	}
+}