[gedit] docs: add API breaks page
- From: Sébastien Wilmet <swilmet src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gedit] docs: add API breaks page
- Date: Tue, 19 Nov 2019 06:59:56 +0000 (UTC)
commit 391a725e1f6b9e4334c6ba87c58581291ad3e52b
Author: Sébastien Wilmet <swilmet gnome org>
Date: Tue Nov 19 06:18:05 2019 +0100
docs: add API breaks page
The previous API breaks were documented on the wiki:
https://wiki.gnome.org/Apps/Gedit/API-Changes
But I prefer to have the API breaks documented alongside the gedit API,
and links to symbols can be added.
docs/reference/api-breaks.xml | 52 +++++++++++++++++++++++++++++++++++++++++++
docs/reference/gedit-docs.xml | 2 ++
docs/reference/meson.build | 3 +++
3 files changed, 57 insertions(+)
---
diff --git a/docs/reference/api-breaks.xml b/docs/reference/api-breaks.xml
new file mode 100644
index 000000000..6d8c2531d
--- /dev/null
+++ b/docs/reference/api-breaks.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+
+<part id="api-breaks">
+ <title>API Breaks</title>
+
+ <para>
+ gedit is a quite old piece of software (created in 1998, at the beginnings
+ of the GNOME project), and as every software, the code evolves during its
+ lifetime. So there are sometimes API breaks for gedit plugins, there are no
+ API stability guarantees.
+ </para>
+
+ <para>
+ When it is possible, instead of directly removing an API, that API is first
+ marked as deprecated, and then removed for the next API break. See the
+ <link linkend="api-index-deprecated">index of deprecated symbols</link>.
+ </para>
+
+ <refsect1>
+ <title>3.34.0 -> 3.35.2</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ All previously deprecated APIs have been removed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <code>GeditDocument:use-gvfs-metadata</code> property has been
+ removed. But there was anyway a warning for not using that property in
+ a gedit plugin.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ For <link linkend="gedit-document-get-metadata">gedit_document_get_metadata()</link>
+ and <link linkend="gedit-document-set-metadata">gedit_document_set_metadata()</link>,
+ the key names should now have the prefix <code>"gedit-"</code> with
+ possibly an additional namespace for the plugin name, for example
+ <code>"gedit-spell-foobar"</code>. So the key names are now the same
+ regardless of the operating system, and the key names should no longer
+ start with <code>"metadata::"</code>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+</part>
diff --git a/docs/reference/gedit-docs.xml b/docs/reference/gedit-docs.xml
index 856ef271e..dd44439fd 100644
--- a/docs/reference/gedit-docs.xml
+++ b/docs/reference/gedit-docs.xml
@@ -27,6 +27,8 @@
<xi:include href="xml/gedit-utils.xml"/>
</chapter>
+ <xi:include href="api-breaks.xml"/>
+
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index c6bb1b97b..e4c3ea6f6 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -94,6 +94,9 @@ gnome.gtkdoc(
scan_args: libgedit_reference_scan_args,
mkdb_args: libgedit_reference_mkdb_args,
fixxref_args: libgedit_reference_fixxref_args,
+ content_files : [
+ 'api-breaks.xml'
+ ],
install: true,
install_dir: join_paths(
gtkdocdir,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]