hoedown/hoedown — pull request #116 by jmendeth (2014-09-02 21:18:50+00:00)
Title: Import improvements from Lanli (and more things)

Lanli is an upcoming HTML sanitizer that will soon be published as a companion to Hoedown.
Most of their code (and phylosophy) is shared, so I'm importing the changes I've done on Lanli. (That forced me to do more improvements in the same commit, instead of splitting them in multiple PR. Sorry about that, really.)

Overall, this PR greatly improves API and code consistency, adds basic documentation and some optimizations.

Here's a list of the changes:

- **Documentation:** added short description for each function in the API.

- **Performance:** `hoedown_escape_html`, `hoedown_escape_href` and `parse_inline` have been optimized and are slightly faster than before. (This made Lanli 10% faster, I don't know about Hoedown yet)

- **API:** following `buffer_new`, all functions that return a pointer to a newly allocated memory area must be declared with `__attribute__ ((malloc))`, in order to properly hint the compiler.

- **API:** `hoedown_buffer_eq[s]` and `hoedown_buffer_set[s]` have been added.

- **Behaviour:** implement a malloc wrapper as we said around #48. This allows us to further simplify the code while still being safe, so we can finally close #48.

- **API:** `extern` is no longer used in `document.h` and `html.h` as it's not needed.

- **Building:** files are now built in C99 mode instead of the default GNU89.

- **Style:** all public headers now closely follow this structure (note: tabs aren't expanded):

~~~ c
/* header.h - short description */

#ifndef HOEDOWN_HEADER_H
#define HOEDOWN_HEADER_H

#include "public_header_1.h"
#include "public_header_2.h"

#include
#include

#ifdef __cplusplus
extern "C" {
#endif

// [Platform-specific hacks]

/*************
* CONSTANTS *
*************/

#define HOEDOWN_CONSTANT 3.1415926535898

typedef enum hoedown_flag {
HOEDOWN_FLAG_ONE = (1 << 0),
HOEDOWN_FLAG_TWO = (1 << 1),
HOEDOWN_FLAG_THREE = (1 << 2)
} hoedown_flag;

typedef enum hoedown_enum {
HOEDOWN_ENUM_ONE,
HOEDOWN_ENUM_TWO,
HOEDOWN_ENUM_THREE
} hoedown_enum;

/*********
* TYPES *
*********/

typedef void *(*hoedown_pointer_type)(void *, size_t);

struct hoedown_type {
type *field;
type field;
other_type **field;
};
typedef struct hoedown_type hoedown_type;

/*************
* FUNCTIONS *
*************/

/* hoedown_function: description */
return_type *hoedown_function(parameter *one, parameter *two);

/* hoedown_function: description */
return_type *hoedown_function(parameter *one, parameter *two);

/* HOEDOWN_HELPER: description */
#define HOEDOWN_HELPER(param, param) \
DEFINITION

#ifdef __cplusplus
}
#endif

#endif /** HOEDOWN_HEADER_H **/
~~~

Sections may be ommited if they're empty.

- **Style:** source files, unlike headers, have no comment at the top.
Exported functions in source files have no comment on them.

- **Style:** descriptions for functions must always be in infinitive.

- **Style:** all files must end with a single newline.

- **Style:** the `init` function should be the first declared function in the header, followed by `new`.

- **Formatting:** trailing whitespace has been removed.

- **API:** these guidelines apply when naming instance functions:

- `hoedown_instance_init` initializes an already-allocated, uninitialized instance.
- `hoedown_instance_new` allocates and initializes a new instance.
- `hoedown_instance_uninit` uninitializes the instance, which is then ready for deallocation (or initialization).
- `hoedown_instance_free` uninitializes and deallocates the instance.
- `hoedown_instance_reset` resets the instance to its recently initialized state.
It's equivalent to calling `uninit` and then `init`, but faster.
- All other methods should only be called on initialized instances.

Following these guidelines, and for consistency with `buffer`, `hoedown_stack_new` has been renamed to `hoedown_stack_init`, and `hoedown_stack_free` to `hoedown_stack_reset`.

- **Behaviour:** before, `hoedown_stack_push` always called `hoedown_stack_grow` to double the current stack size, resulting in repeated grows. Now, it only grows when there's no room for more items, and it grows to `(size + 1) * 2`, resulting in different patterns.

- **API:** exported methods now follow the `const uint8_t *data, size_t size` convention to accept input, as well as the `hoedown_buffer *ob` convention for output.

- **API:** `typedef` not only structs, but enums, and use the enum type instead of `unsigned int`.

- **API:** flags should have a plural name, as in `hoedown_extensions` or `hoedown_html_flags`.
Regular enums should have a singular name, as in `hoedown_html_tag` or `hoedown_action`.