doc: Add "since" tag to documentation

The following Python script was used to compute "Since: 1.X" tags,
based on the first version where a symbol became officially supported.

This script requires a concatenation of the the cairo public headers
for the officially supported beckends to be available as
"../../includes/1.X.0.h".

from sys import argv
import re

syms = {}

def stripcomments(text):
    def replacer(match):
        s = match.group(0)
        if s.startswith('/'):
            return ""
        else:
            return s
    pattern = re.compile(
        r'//.*?$|/\*.*?\*/|\'(?:\\.|[^\\\'])*\'|"(?:\\.|[^\\"])*"',
        re.DOTALL | re.MULTILINE
    )
    return re.sub(pattern, replacer, text)

for minor in range(12,-2,-2):
    version = "1.%d" % minor
    names = re.split('([A-Za-z0-9_]+)', stripcomments(open("../../includes/%s.0.h" % version).read()))
    for s in names: syms[s] = version

for filename in argv[1:]:
    is_public = False
    lines = open(filename, "r").read().split("\n")
    newlines = []
    for i in range(len(lines)):
        if lines[i] == "/**":
            last_sym = lines[i+1][2:].strip().replace(":", "")
            is_public = last_sym.lower().startswith("cairo")
        elif is_public and lines[i] == " **/":
            if last_sym in syms:
                v = syms[last_sym]
                if re.search("Since", newlines[-1]): newlines = newlines[:-1]
                if newlines[-1].strip() != "*": newlines.append(" *")
                newlines.append(" * Since: %s" % v)
            else:
                print "%s (%d): Cannot determine the version in which '%s' was introduced" % (filename, i, last_sym)
        newlines.append(lines[i])

    out = open(filename, "w")
    out.write("\n".join(newlines))
    out.close()

1 files changed, 30 insertions, 0 deletions

diff --git a/src/cairo-font-options.c b/src/cairo-font-options.c
index 709c5f807..ccbe16d42 100644
--- a/src/cairo-font-options.c
+++ b/src/cairo-font-options.c
@@ -98,6 +98,8 @@ _cairo_font_options_init_copy (cairo_font_options_t		*options,
  *   valid pointer; if memory cannot be allocated, then a special
  *   error object is returned where all operations on the object do nothing.
  *   You can check for this with cairo_font_options_status().
+ *
+ * Since: 1.0
  **/
 cairo_font_options_t *
 cairo_font_options_create (void)
@@ -127,6 +129,8 @@ cairo_font_options_create (void)
  *   valid pointer; if memory cannot be allocated, then a special
  *   error object is returned where all operations on the object do nothing.
  *   You can check for this with cairo_font_options_status().
+ *
+ * Since: 1.0
  **/
 cairo_font_options_t *
 cairo_font_options_copy (const cairo_font_options_t *original)
@@ -153,6 +157,8 @@ cairo_font_options_copy (const cairo_font_options_t *original)
  *
  * Destroys a #cairo_font_options_t object created with
  * cairo_font_options_create() or cairo_font_options_copy().
+ *
+ * Since: 1.0
  **/
 void
 cairo_font_options_destroy (cairo_font_options_t *options)
@@ -171,6 +177,8 @@ cairo_font_options_destroy (cairo_font_options_t *options)
  * font options object
  *
  * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
+ *
+ * Since: 1.0
  **/
 cairo_status_t
 cairo_font_options_status (cairo_font_options_t *options)
@@ -193,6 +201,8 @@ slim_hidden_def (cairo_font_options_status);
  * existing values. This operation can be thought of as somewhat
  * similar to compositing @other onto @options with the operation
  * of %CAIRO_OPERATOR_OVER.
+ *
+ * Since: 1.0
  **/
 void
 cairo_font_options_merge (cairo_font_options_t       *options,
@@ -229,6 +239,8 @@ slim_hidden_def (cairo_font_options_merge);
  * Return value: %TRUE if all fields of the two font options objects match.
  *	Note that this function will return %FALSE if either object is in
  *	error.
+ *
+ * Since: 1.0
  **/
 cairo_bool_t
 cairo_font_options_equal (const cairo_font_options_t *options,
@@ -262,6 +274,8 @@ slim_hidden_def (cairo_font_options_equal);
  * Return value: the hash value for the font options object.
  *   The return value can be cast to a 32-bit type if a
  *   32-bit hash value is needed.
+ *
+ * Since: 1.0
  **/
 unsigned long
 cairo_font_options_hash (const cairo_font_options_t *options)
@@ -284,6 +298,8 @@ slim_hidden_def (cairo_font_options_hash);
  *
  * Sets the antialiasing mode for the font options object. This
  * specifies the type of antialiasing to do when rendering text.
+ *
+ * Since: 1.0
  **/
 void
 cairo_font_options_set_antialias (cairo_font_options_t *options,
@@ -303,6 +319,8 @@ slim_hidden_def (cairo_font_options_set_antialias);
  * Gets the antialiasing mode for the font options object.
  *
  * Return value: the antialiasing mode
+ *
+ * Since: 1.0
  **/
 cairo_antialias_t
 cairo_font_options_get_antialias (const cairo_font_options_t *options)
@@ -323,6 +341,8 @@ cairo_font_options_get_antialias (const cairo_font_options_t *options)
  * the display device when rendering with an antialiasing mode of
  * %CAIRO_ANTIALIAS_SUBPIXEL. See the documentation for
  * #cairo_subpixel_order_t for full details.
+ *
+ * Since: 1.0
  **/
 void
 cairo_font_options_set_subpixel_order (cairo_font_options_t   *options,
@@ -343,6 +363,8 @@ slim_hidden_def (cairo_font_options_set_subpixel_order);
  * See the documentation for #cairo_subpixel_order_t for full details.
  *
  * Return value: the subpixel order for the font options object
+ *
+ * Since: 1.0
  **/
 cairo_subpixel_order_t
 cairo_font_options_get_subpixel_order (const cairo_font_options_t *options)
@@ -443,6 +465,8 @@ _cairo_font_options_get_round_glyph_positions (const cairo_font_options_t *optio
  * This controls whether to fit font outlines to the pixel grid,
  * and if so, whether to optimize for fidelity or contrast.
  * See the documentation for #cairo_hint_style_t for full details.
+ *
+ * Since: 1.0
  **/
 void
 cairo_font_options_set_hint_style (cairo_font_options_t *options,
@@ -463,6 +487,8 @@ slim_hidden_def (cairo_font_options_set_hint_style);
  * See the documentation for #cairo_hint_style_t for full details.
  *
  * Return value: the hint style for the font options object
+ *
+ * Since: 1.0
  **/
 cairo_hint_style_t
 cairo_font_options_get_hint_style (const cairo_font_options_t *options)
@@ -482,6 +508,8 @@ cairo_font_options_get_hint_style (const cairo_font_options_t *options)
  * controls whether metrics are quantized to integer values in
  * device units.
  * See the documentation for #cairo_hint_metrics_t for full details.
+ *
+ * Since: 1.0
  **/
 void
 cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
@@ -502,6 +530,8 @@ slim_hidden_def (cairo_font_options_set_hint_metrics);
  * See the documentation for #cairo_hint_metrics_t for full details.
  *
  * Return value: the metrics hinting mode for the font options object
+ *
+ * Since: 1.0
  **/
 cairo_hint_metrics_t
 cairo_font_options_get_hint_metrics (const cairo_font_options_t *options)