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, 16 insertions, 0 deletions

diff --git a/src/cairo-script-surface.c b/src/cairo-script-surface.c
index 89cf5259f..a2de7d657 100644
--- a/src/cairo-script-surface.c
+++ b/src/cairo-script-surface.c
@@ -3744,6 +3744,8 @@ _cairo_script_context_create (cairo_output_stream_t *stream)
  * This function always returns a valid pointer, but it will return a
  * pointer to a "nil" device if an error such as out of memory
  * occurs. You can use cairo_device_status() to check for this.
+ *
+ * Since: 1.12
  **/
 cairo_device_t *
 cairo_script_create (const char *filename)
@@ -3773,6 +3775,8 @@ cairo_script_create (const char *filename)
  * This function always returns a valid pointer, but it will return a
  * pointer to a "nil" device if an error such as out of memory
  * occurs. You can use cairo_device_status() to check for this.
+ *
+ * Since: 1.12
  **/
 cairo_device_t *
 cairo_script_create_for_stream (cairo_write_func_t	 write_func,
@@ -3795,6 +3799,8 @@ cairo_script_create_for_stream (cairo_write_func_t	 write_func,
  * @len:the length of the sting to write, or -1 to use strlen()
  *
  * Emit a string verbatim into the script.
+ *
+ * Since: 1.12
  **/
 void
 cairo_script_write_comment (cairo_device_t *script,
@@ -3817,6 +3823,8 @@ cairo_script_write_comment (cairo_device_t *script,
  * @mode: the new mode
  *
  * Change the output mode of the script
+ *
+ * Since: 1.12
  **/
 void
 cairo_script_set_mode (cairo_device_t *script,
@@ -3834,6 +3842,8 @@ cairo_script_set_mode (cairo_device_t *script,
  * Queries the script for its current output mode.
  *
  * Return value: the current output mode of the script
+ *
+ * Since: 1.12
  **/
 cairo_script_mode_t
 cairo_script_get_mode (cairo_device_t *script)
@@ -3859,6 +3869,8 @@ cairo_script_get_mode (cairo_device_t *script)
  * This function always returns a valid pointer, but it will return a
  * pointer to a "nil" surface if an error such as out of memory
  * occurs. You can use cairo_surface_status() to check for this.
+ *
+ * Since: 1.12
  **/
 cairo_surface_t *
 cairo_script_surface_create (cairo_device_t *script,
@@ -3902,6 +3914,8 @@ slim_hidden_def (cairo_script_surface_create);
  * This function always returns a valid pointer, but it will return a
  * pointer to a "nil" surface if an error such as out of memory
  * occurs. You can use cairo_surface_status() to check for this.
+ *
+ * Since: 1.12
  **/
 cairo_surface_t *
 cairo_script_surface_create_for_target (cairo_device_t *script,
@@ -3939,6 +3953,8 @@ cairo_script_surface_create_for_target (cairo_device_t *script,
  * Converts the record operations in @recording_surface into a script.
  *
  * Return value: #CAIRO_STATUS_SUCCESS on successful completion or an error code.
+ *
+ * Since: 1.12
  **/
 cairo_status_t
 cairo_script_from_recording_surface (cairo_device_t *script,