[libxml2] Deprecate IDREF-related functions in valid.h

[Nick Wellnhofer <nwellnhof src gnome org>]

commit 004fe9de53ec33133e6cafbe5850ebc9a1d1cdcf
Author: Nick Wellnhofer <wellnhofer aevum de>
Date:   Sun Feb 20 19:02:31 2022 +0100

    Deprecate IDREF-related functions in valid.h
    
    These functions are only needed internally for validation.
    
    xmlGetRefs is inherently unsafe because the ref table isn't updated
    if attributes are removed (unlike the ids table).
    
    None of the Ubuntu 20.04 packages depending on libxml2 use any of these
    functions (except xmlFreeRefTable in libxslt), so it seems perfectly
    safe to deprecate them.
    
    Remove xmlIsRef and xmlRemoveRef from the Python bindings.

 include/libxml/valid.h |  5 +++++
 python/generator.py    |  7 +++++++
 valid.c                | 10 ++++++++++
 3 files changed, 22 insertions(+)
---
diff --git a/include/libxml/valid.h b/include/libxml/valid.h
index 15c9772c..3eaf84ad 100644
--- a/include/libxml/valid.h
+++ b/include/libxml/valid.h
@@ -283,20 +283,25 @@ XMLPUBFUN int XMLCALL
                                        xmlAttrPtr attr);
 
 /* IDREFs */
+XML_DEPRECATED
 XMLPUBFUN xmlRefPtr XMLCALL
                xmlAddRef              (xmlValidCtxtPtr ctxt,
                                        xmlDocPtr doc,
                                        const xmlChar *value,
                                        xmlAttrPtr attr);
+XML_DEPRECATED
 XMLPUBFUN void XMLCALL
                xmlFreeRefTable        (xmlRefTablePtr table);
+XML_DEPRECATED
 XMLPUBFUN int XMLCALL
                xmlIsRef               (xmlDocPtr doc,
                                        xmlNodePtr elem,
                                        xmlAttrPtr attr);
+XML_DEPRECATED
 XMLPUBFUN int XMLCALL
                xmlRemoveRef           (xmlDocPtr doc,
                                        xmlAttrPtr attr);
+XML_DEPRECATED
 XMLPUBFUN xmlListPtr XMLCALL
                xmlGetRefs             (xmlDocPtr doc,
                                        const xmlChar *ID);
diff --git a/python/generator.py b/python/generator.py
index 59d45e00..299bf2f2 100755
--- a/python/generator.py
+++ b/python/generator.py
@@ -289,7 +289,14 @@ skip_impl = (
     'xmlSaveFormatFileTo',
 )
 
+deprecated_funcs = {
+    'xmlIsRef': True,
+    'xmlRemoveRef': True,
+}
+
 def skip_function(name):
+    if name in deprecated_funcs:
+        return 1
     if name[0:12] == "xmlXPathWrap":
         return 1
     if name == "xmlFreeParserCtxt":
diff --git a/valid.c b/valid.c
index 23f868a3..d1df2d50 100644
--- a/valid.c
+++ b/valid.c
@@ -3000,6 +3000,8 @@ xmlDummyCompare(const void *data0 ATTRIBUTE_UNUSED,
  * @value:  the value name
  * @attr:  the attribute holding the Ref
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Register a new ref declaration
  *
  * Returns NULL if not, otherwise the new xmlRefPtr
@@ -3100,6 +3102,8 @@ failed:
  * xmlFreeRefTable:
  * @table:  An ref table
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Deallocate the memory used by an Ref hash table.
  */
 void
@@ -3113,6 +3117,8 @@ xmlFreeRefTable(xmlRefTablePtr table) {
  * @elem:  the element carrying the attribute
  * @attr:  the attribute
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Determine whether an attribute is of type Ref. In case we have DTD(s)
  * then this is simple, otherwise we use an heuristic: name Ref (upper
  * or lowercase).
@@ -3155,6 +3161,8 @@ xmlIsRef(xmlDocPtr doc, xmlNodePtr elem, xmlAttrPtr attr) {
  * @doc:  the document
  * @attr:  the attribute
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Remove the given attribute from the Ref table maintained internally.
  *
  * Returns -1 if the lookup failed and 0 otherwise
@@ -3211,6 +3219,8 @@ xmlRemoveRef(xmlDocPtr doc, xmlAttrPtr attr) {
  * @doc:  pointer to the document
  * @ID:  the ID value
  *
+ * DEPRECATED, do not use. This function will be removed from the public API.
+ *
  * Find the set of references for the supplied ID.
  *
  * Returns NULL if not found, otherwise node set for the ID.